diff --git a/.github/workflows/publish-preprod.yml b/.github/workflows/publish-preprod.yml deleted file mode 100644 index 416031df..00000000 --- a/.github/workflows/publish-preprod.yml +++ /dev/null @@ -1,76 +0,0 @@ -name: Publish Docs in Preprod -on: - push: - branches: - - main - workflow_dispatch: -env: - BASEURL: "/preprod/" - -jobs: - build: - name: Build Docs - runs-on: ubuntu-latest - - steps: - - name: Checkout the docs repo - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: 19.7.0 - - - name: Install dependencies - run: npm ci - - - name: Clean the build - run: rm -rf ./build - - - name: Generate the docs - run: npm run build - - - name: Stage docs for the deploy-preprod job - uses: actions/upload-artifact@master - with: - name: build - path: ./build - - deploy-preprod: - name: Deploy to Preprod - needs: build - runs-on: ubuntu-latest - - steps: - - name: Get docs for the build job - uses: actions/download-artifact@master - with: - name: build - path: ./build - - - name: Update S3 with the docs - uses: jakejarvis/s3-sync-action@master - with: - args: --acl public-read --follow-symlinks --delete - env: - AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }} - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - SOURCE_DIR: 'build' - DEST_DIR: 'preprod' - - invalidate-cloudfront: - name: Invalidate CloudFront - needs: [build, deploy-preprod] - runs-on: ubuntu-latest - - steps: - - name: Invalidate CloudFront for preprod - uses: chetan/invalidate-cloudfront-action@v2 - if: ${{ github.ref }} == ${{ env.RELEASE_DOCS_BRANCH_REF }} - env: - PATHS: '/preprod/*' - AWS_REGION: 'us-east-2' - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - DISTRIBUTION: ${{ secrets.DISTRIBUTION_ID }} diff --git a/.github/workflows/publish-prod.yml b/.github/workflows/publish-prod.yml deleted file mode 100644 index c0b30aab..00000000 --- a/.github/workflows/publish-prod.yml +++ /dev/null @@ -1,72 +0,0 @@ -name: Publish Docs in Prod -on: - workflow_dispatch: -env: - BASEURL: "/" - -jobs: - build: - name: Build Docs - runs-on: ubuntu-latest - - steps: - - name: Checkout the docs repo - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: 19.7.0 - - - name: Install dependencies - run: npm ci - - - name: Clean the build - run: rm -rf ./build - - - name: Generate the docs - run: npm run build - - - name: Stage docs for the deploy-preprod job - uses: actions/upload-artifact@master - with: - name: build - path: ./build - - deploy-prod: - name: Deploy to Production - needs: build - runs-on: ubuntu-latest - - steps: - - name: Get docs for the build job - uses: actions/download-artifact@master - with: - name: build - path: ./build - - - name: Update S3 with the docs - uses: jakejarvis/s3-sync-action@master - with: - args: --acl public-read --follow-symlinks --delete - env: - AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }} - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - SOURCE_DIR: 'build' - - invalidate-cloudfront: - name: Invalidate CloudFront - needs: [build, deploy-prod] - runs-on: ubuntu-latest - - steps: - - name: Invalidate CloudFront for preprod - uses: chetan/invalidate-cloudfront-action@v2 - if: ${{ github.ref }} == ${{ env.RELEASE_DOCS_BRANCH_REF }} - env: - PATHS: '/*' - AWS_REGION: 'us-east-2' - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - DISTRIBUTION: ${{ secrets.DISTRIBUTION_ID }} diff --git a/.github/workflows/main.yaml b/.github/workflows/publish.yaml similarity index 100% rename from .github/workflows/main.yaml rename to .github/workflows/publish.yaml diff --git a/docs/aws/gitops-catalog.mdx b/docs/aws/gitops-catalog.mdx new file mode 100644 index 00000000..7b9ebeeb --- /dev/null +++ b/docs/aws/gitops-catalog.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: aws +sidebar_label: GitOps Catalog +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: using the kubefirst gitops catalog +keywords: + - aws +image: 'https://docs.kubefirst.io/img/logo.svg' +--- + +import GitOpsCatalog from '@site/docs/common/gitops-catalog.mdx'; + + diff --git a/docs/aws/quick-start/install/ui.mdx b/docs/aws/quick-start/install/ui.mdx index a7121c75..d6ca774f 100644 --- a/docs/aws/quick-start/install/ui.mdx +++ b/docs/aws/quick-start/install/ui.mdx @@ -26,9 +26,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -46,14 +46,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/docs/civo/gitops-catalog.mdx b/docs/civo/gitops-catalog.mdx new file mode 100644 index 00000000..b448ff3c --- /dev/null +++ b/docs/civo/gitops-catalog.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: civo +sidebar_label: GitOps Catalog +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: using the kubefirst gitops catalog +keywords: + - aws +image: 'https://docs.kubefirst.io/img/logo.svg' +--- + +import GitOpsCatalog from '@site/docs/common/gitops-catalog.mdx'; + + diff --git a/docs/civo/quick-start/install/ui.mdx b/docs/civo/quick-start/install/ui.mdx index a7121c75..d6ca774f 100644 --- a/docs/civo/quick-start/install/ui.mdx +++ b/docs/civo/quick-start/install/ui.mdx @@ -26,9 +26,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -46,14 +46,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/docs/common/gitops-catalog.mdx b/docs/common/gitops-catalog.mdx new file mode 100644 index 00000000..a38fc216 --- /dev/null +++ b/docs/common/gitops-catalog.mdx @@ -0,0 +1,83 @@ +# GitOps Catalog + +After your kubefirst cluster has been provisioned, you can optionally leverage the Kubefirst GitOps Catalog. + +The GitOps Catalog is a curated collection of Kubernetes applications that can be deployed directly to your kubefirst cluster(s). + +For more information regarding applications that are generally available, check out the GitOps Catalog [repository](https://github.com/kubefirst/gitops-catalog). + +## Using the catalog + +After your cluster has been provisioned, you're able to click on a button to **open kubefirst console**: + +![Cluster provision complete](../img/common/catalog/button.png) + +Once this button has been clicked, you're presented with the **Services Overview** page: + +![Services Overview page](../img/common/catalog/page.png) + +This page shows the services that have been provisioned to your kubefirst management cluster. Default applications will show up in this list as well. + +You can click on the **GitOps catalog** button to show the catalog: + +![GitOps catalog](../img/common/catalog/services.png) + +From here, you can click **Install** on any of the available services to deploy them to your cluster. + +## How this works + +When you opt to install any of the available services from the GitOps Catalog, the kubefirst API formats and commits a set of files to your gitops repository. + +Then, Argo CD is asked to refresh the upstream registry to synchronize the newly deployed application. + +Since the deployment of these applications is done directly in your gitops repository, you have full ownership to then customize these applications by adjusting their content within your gitops repository. + +For example - consider the following sample deployment of Kuberntes Dashboard: + +```yaml +--- +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: kubernetes-dashboard + namespace: argocd +spec: + project: default + source: + repoURL: 'https://kubernetes.github.io/dashboard' + targetRevision: 6.0.0 + chart: kubernetes-dashboard + destination: + server: 'https://kubernetes.default.svc' + namespace: kubernetes-dashboard + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true + +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: k8s-dashboard-clusterrole + annotations: + argocd.argoproj.io/sync-wave: '0' +subjects: + - kind: ServiceAccount + name: k8s-dashboard-sa + namespace: default +roleRef: + kind: ClusterRole + name: admin + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: k8s-dashboard-sa + namespace: default +``` + +If you'd like to change any of the helm chart values, change the helm chart version, or add any additional resources, you simply edit this file and Argo CD will detect the changes from your upstream gitops repository and synchronize. diff --git a/docs/common/install-clouds.mdx b/docs/common/install-clouds.mdx index 001977fb..3ecc9d56 100644 --- a/docs/common/install-clouds.mdx +++ b/docs/common/install-clouds.mdx @@ -18,9 +18,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -38,14 +38,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/docs/img/common/catalog/button.png b/docs/img/common/catalog/button.png new file mode 100644 index 00000000..138b8c64 Binary files /dev/null and b/docs/img/common/catalog/button.png differ diff --git a/docs/img/common/catalog/page.png b/docs/img/common/catalog/page.png new file mode 100644 index 00000000..331c4060 Binary files /dev/null and b/docs/img/common/catalog/page.png differ diff --git a/docs/img/common/catalog/services.png b/docs/img/common/catalog/services.png new file mode 100644 index 00000000..e1c4a1c1 Binary files /dev/null and b/docs/img/common/catalog/services.png differ diff --git a/sidebars.js b/sidebars.js index 81099db1..bcb72769 100644 --- a/sidebars.js +++ b/sidebars.js @@ -40,6 +40,7 @@ const sidebars = { }, ], }, + 'civo/gitops-catalog', 'aws/deprovision', 'aws/faq', 'aws/credits', @@ -65,6 +66,7 @@ const sidebars = { }, ], }, + 'civo/gitops-catalog', 'civo/deprovision', 'civo/faq', 'civo/credits', diff --git a/versioned_docs/version-2.1/aws/quick-start/install/ui.mdx b/versioned_docs/version-2.1/aws/quick-start/install/ui.mdx index a7121c75..d6ca774f 100644 --- a/versioned_docs/version-2.1/aws/quick-start/install/ui.mdx +++ b/versioned_docs/version-2.1/aws/quick-start/install/ui.mdx @@ -26,9 +26,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -46,14 +46,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/versioned_docs/version-2.1/civo/quick-start/install/ui.mdx b/versioned_docs/version-2.1/civo/quick-start/install/ui.mdx index a7121c75..d6ca774f 100644 --- a/versioned_docs/version-2.1/civo/quick-start/install/ui.mdx +++ b/versioned_docs/version-2.1/civo/quick-start/install/ui.mdx @@ -26,9 +26,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -46,14 +46,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/versioned_docs/version-2.1/common/install-clouds.mdx b/versioned_docs/version-2.1/common/install-clouds.mdx index 001977fb..3ecc9d56 100644 --- a/versioned_docs/version-2.1/common/install-clouds.mdx +++ b/versioned_docs/version-2.1/common/install-clouds.mdx @@ -18,9 +18,9 @@ favorite git provider. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace kubefirst/kubefirst +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) @@ -38,14 +38,14 @@ run on the ARM architecture. helm repo add kubefirst https://charts.kubefirst.com helm repo update -helm install kubefirst --create-namespace \ +helm install kubefirst --namespace kubefirst --create-namespace \ --set=mongodb.image.repository=arm64v8/mongo \ --set=mongodb.image.tag=latest \ --set=mongodb.persistence.mountPath=/data/db \ --set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ kubefirst/kubefirst -k port-forward svc/kubefirst-console 8080:8080 +kubectl port-forward svc/kubefirst-console 8080:8080 ``` Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) diff --git a/versioned_docs/version-2.2/aws/advanced/certificates.mdx b/versioned_docs/version-2.2/aws/advanced/certificates.mdx new file mode 100644 index 00000000..666574b5 --- /dev/null +++ b/versioned_docs/version-2.2/aws/advanced/certificates.mdx @@ -0,0 +1,29 @@ +--- +title: Certificates +--- + +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +## SSL Certificates + +In cloud versions of the kubefirst platform, we use [cert-manager](https://cert-manager.io/) with a [Let's Encrypt](https://letsencrypt.org) ClusterIssuer for TLS encryption to all of our services on Ingress. These certificates are requested automatically, and will auto-renew. + +On local versions of the kubefirst platform, we leverage [mkcert](https://github.com/FiloSottile/mkcert) to generate certificates for a domain we host at `kubefirst.dev`. + +To trust mkcerts in your browser, run + +```bash +mkcert -install +``` diff --git a/versioned_docs/version-2.2/aws/advanced/install.mdx b/versioned_docs/version-2.2/aws/advanced/install.mdx new file mode 100644 index 00000000..3841e114 --- /dev/null +++ b/versioned_docs/version-2.2/aws/advanced/install.mdx @@ -0,0 +1,55 @@ +--- +hide_title: true +sidebar_label: Install +sidebar_position: 2 +custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: the installation process for kubefirst cli +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +import GitHubInstall from '@site/docs/aws/partials/github/_install.mdx' +import GitLabInstall from '@site/docs/aws/partials/gitlab/_install.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/aws/advanced/security.mdx b/versioned_docs/version-2.2/aws/advanced/security.mdx new file mode 100644 index 00000000..98bdbed9 --- /dev/null +++ b/versioned_docs/version-2.2/aws/advanced/security.mdx @@ -0,0 +1,29 @@ +--- +title: Security +--- + +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +## Installation Account + +kubefirst runs against your public cloud provider and leverages your personal cloud credentials in order to conduct the provisioning of the kubefirst platform. We do not embed your credentials into the platform in any way, they are only used during the installation process. + +## Granular Kubernetes Service Accounts with Explicit IAM Roles for Cloud Access + +Each of our platform services has the potential to require access to cloud resources to take advantage of artifact storage, database access, KMS encryption, or things of that nature. Each service account on the platform comes with a dedicated least privilege IAM policy to grant granular and controlled access to cloud resources on the platform. + +## Additional Layers of Security + +GitLab, Vault, Atlantis, and External Secrets Operator have had additional security measures implemented in accordance with the respective applications own security guidelines. Each of these have been implemented to provide reasonable starting points on top of a solid security posture for your core application dependencies. diff --git a/versioned_docs/version-2.2/aws/advanced/styles.module.css b/versioned_docs/version-2.2/aws/advanced/styles.module.css new file mode 100644 index 00000000..a6e39ce9 --- /dev/null +++ b/versioned_docs/version-2.2/aws/advanced/styles.module.css @@ -0,0 +1,13 @@ +.gitlab { +color: #fc6d26; +} +.gitlab[aria-selected='true'] { +border-bottom-color: #fc6d26; +} + +.github { +color: black; +} +.github[aria-selected='true'] { +border-bottom-color: black; +} \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/credits.mdx b/versioned_docs/version-2.2/aws/credits.mdx new file mode 100644 index 00000000..186c6481 --- /dev/null +++ b/versioned_docs/version-2.2/aws/credits.mdx @@ -0,0 +1,11 @@ +--- +hide_title: true +sidebar_label: Credits +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: how to destroy your kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Credits from "@site/docs/common/credits.mdx" + + diff --git a/versioned_docs/version-2.2/aws/deprovision.mdx b/versioned_docs/version-2.2/aws/deprovision.mdx new file mode 100644 index 00000000..f738c06f --- /dev/null +++ b/versioned_docs/version-2.2/aws/deprovision.mdx @@ -0,0 +1,11 @@ +--- +hide_title: true +sidebar_label: Deprovision +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: how to destroy your kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Deprovision from '@site/docs/common/deprovision.mdx' + + diff --git a/versioned_docs/version-2.2/aws/explore/argocd.mdx b/versioned_docs/version-2.2/aws/explore/argocd.mdx new file mode 100644 index 00000000..9f4f59f0 --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/argocd.mdx @@ -0,0 +1,8 @@ +--- +title: Argo CD +sidebar_position: 1 +--- + +import ExploreArgocd from "@site/docs/common/argocd.mdx" + + diff --git a/versioned_docs/version-2.2/aws/explore/gitops.mdx b/versioned_docs/version-2.2/aws/explore/gitops.mdx new file mode 100644 index 00000000..b1ac43cd --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/gitops.mdx @@ -0,0 +1,9 @@ +--- +title: GitOps +sidebar_position: 2 +--- + + +import ExploreGitOps from "@site/docs/common/gitops.mdx" + + diff --git a/versioned_docs/version-2.2/aws/explore/metaphor.mdx b/versioned_docs/version-2.2/aws/explore/metaphor.mdx new file mode 100644 index 00000000..6ff78d11 --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/metaphor.mdx @@ -0,0 +1,8 @@ +--- +title: Metaphor +sidebar_position: 3 +--- + +import ExploreMetaphor from "@site/docs/common/metaphor.mdx" + + diff --git a/versioned_docs/version-2.2/aws/explore/platform.mdx b/versioned_docs/version-2.2/aws/explore/platform.mdx new file mode 100644 index 00000000..53e73d9f --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/platform.mdx @@ -0,0 +1,8 @@ +--- +title: Telemetry +sidebar_position: 6 +--- + +import ExploreTelemetry from "@site/docs/common/telemetry.mdx" + + diff --git a/versioned_docs/version-2.2/aws/explore/terraform.mdx b/versioned_docs/version-2.2/aws/explore/terraform.mdx new file mode 100644 index 00000000..e89177d9 --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/terraform.mdx @@ -0,0 +1,8 @@ +--- +title: Terraform & Atlantis +sidebar_position: 5 +--- + +import ExploreTerraform from "@site/docs/common/terraform.mdx" + + diff --git a/versioned_docs/version-2.2/aws/explore/user-creation.mdx b/versioned_docs/version-2.2/aws/explore/user-creation.mdx new file mode 100644 index 00000000..6b55488c --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/user-creation.mdx @@ -0,0 +1,19 @@ +--- +title: User Creation +sidebar_position: 5 +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; + +import GitHubUserCreation from '@site/docs/civo/partials/github/_user-creation.mdx' +import GitLabUserCreation from '@site/docs/civo/partials/gitlab/_user-creation.mdx' + + + + + + + + + \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/explore/vault.mdx b/versioned_docs/version-2.2/aws/explore/vault.mdx new file mode 100644 index 00000000..73fefddd --- /dev/null +++ b/versioned_docs/version-2.2/aws/explore/vault.mdx @@ -0,0 +1,8 @@ +--- +title: Vault +sidebar_position: 4 +--- + +import ExploreVault from "@site/docs/common/vault.mdx" + + diff --git a/versioned_docs/version-2.2/aws/faq.mdx b/versioned_docs/version-2.2/aws/faq.mdx new file mode 100644 index 00000000..4ea1b652 --- /dev/null +++ b/versioned_docs/version-2.2/aws/faq.mdx @@ -0,0 +1,11 @@ +--- +hide_title: true +sidebar_label: FAQ +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: frequently asked quesitons about the platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import FAQ from "@site/docs/common/faq.mdx" + + diff --git a/versioned_docs/version-2.2/aws/gitops-catalog.mdx b/versioned_docs/version-2.2/aws/gitops-catalog.mdx new file mode 100644 index 00000000..7b9ebeeb --- /dev/null +++ b/versioned_docs/version-2.2/aws/gitops-catalog.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: aws +sidebar_label: GitOps Catalog +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: using the kubefirst gitops catalog +keywords: + - aws +image: 'https://docs.kubefirst.io/img/logo.svg' +--- + +import GitOpsCatalog from '@site/docs/common/gitops-catalog.mdx'; + + diff --git a/versioned_docs/version-2.2/aws/overview.mdx b/versioned_docs/version-2.2/aws/overview.mdx new file mode 100644 index 00000000..e184ae70 --- /dev/null +++ b/versioned_docs/version-2.2/aws/overview.mdx @@ -0,0 +1,74 @@ +--- +hide_title: true +sidebar_label: Overview +sidebar_position: 1 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: an overview of the kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +import GitHubOverview from '@site/docs/aws/partials/github/_overview.mdx' +import GitLabOverview from '@site/docs/aws/partials/gitlab/_overview.mdx' + +# Overview + +The aws provisioning process will: +- create a vpc, subnets, iam, and eks cluster in your specified aws account + +- create a gitops git repository from our gitops-template, customized for you, and store it in your git provider +- install argocd and register it with your gitops repo so that your main branch powers the platform +- install all the platform apps using argocd gitops preconfigured sync waves (gitops repo `/registry` folder) +- apply terraform to configure Vault (gitops repo `/terraform/vault` folder) +- bind a webhook to atlantis to automate terraform executions +- integrate argo workflows with your git provider +- install argo workflow automation to build containers, publish charts, and provide gitops delivery pipelines +- install a sample app git repository that uses this automation to demonstrate gitops app delivery and promotion (metaphor repo) + +![kubefirst AWS with GitHub Cluster Diagram](../img/aws/github/installation-diagram-light.png#light-mode)![kubefirst AWS with GitHub Cluster Diagram](../img/aws/github/installation-diagram-dark.png#dark-mode) + +# Applications + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/aws/partials/common/_cluster-connectivity.mdx b/versioned_docs/version-2.2/aws/partials/common/_cluster-connectivity.mdx new file mode 100644 index 00000000..8ef8fac6 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/common/_cluster-connectivity.mdx @@ -0,0 +1,13 @@ +## Connecting to Kubernetes + +To connect to your new Kubernetes cluster, run + +```bash +export KUBECONFIG=~/.k1/kubeconfig +``` + +To view all cluster pods, run + +```bash +kubectl get pods -A +``` diff --git a/versioned_docs/version-2.2/aws/partials/common/_installed-applications.mdx b/versioned_docs/version-2.2/aws/partials/common/_installed-applications.mdx new file mode 100644 index 00000000..7e007876 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/common/_installed-applications.mdx @@ -0,0 +1,3 @@ +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../overview.mdx#platforms-details). diff --git a/versioned_docs/version-2.2/aws/partials/common/_prerequisites.mdx b/versioned_docs/version-2.2/aws/partials/common/_prerequisites.mdx new file mode 100644 index 00000000..b30b27a6 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/common/_prerequisites.mdx @@ -0,0 +1,25 @@ +## Prerequisites + +### Local Prerequisites + +If you are on macOS, and have [Homebrew](https://brew.sh) installed, you can run: + +```shell +brew install kubefirst/tools/kubefirst +``` + +To upgrade an existing kubefirst CLI to the latest version run: + +```shell +brew update +brew upgrade kubefirst +``` + +There are other ways to install kubefirst for different operating systems, architectures, and containerized environments. See our [installation README](https://github.com/kubefirst/kubefirst/blob/main/build/README.md) for details. + +#### AWS Prerequisites + +1. Create an AWS account with billing enabled. +2. Establish a public hosted zone with DNS routing established ([docs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)). +3. Connect with [Administrator Access](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AdministratorAccessserviceLevelSummary) IAM credentials to your AWS account ([docs](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)). +4. Our Homebrew package will automatically install the [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) dependency. If you use another installation method, you will need to install this utility. \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/partials/common/_root-credentials-cmd.mdx b/versioned_docs/version-2.2/aws/partials/common/_root-credentials-cmd.mdx new file mode 100644 index 00000000..c84858a3 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/common/_root-credentials-cmd.mdx @@ -0,0 +1,12 @@ +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst aws root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +:::note the `kubefirst aws root-credentials` command was introduced in 2.0.1 +::: diff --git a/versioned_docs/version-2.2/aws/partials/github/_cluster-create.mdx b/versioned_docs/version-2.2/aws/partials/github/_cluster-create.mdx new file mode 100644 index 00000000..ebdeab3d --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/github/_cluster-create.mdx @@ -0,0 +1,13 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitHub token in addition to the appropriate values for your new platform. + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxx + +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --domain-name your-company.io \ + --cluster-name kubefirst-mgmt \ + --github-org your-github-organization-name +``` diff --git a/versioned_docs/version-2.2/aws/partials/github/_install.mdx b/versioned_docs/version-2.2/aws/partials/github/_install.mdx new file mode 100644 index 00000000..0d70307c --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/github/_install.mdx @@ -0,0 +1,71 @@ +## AWS Platform Installation using GitHub + +**kubefirst** is the name of our command line tool that installs the kubefirst platform and provides some platform conveniences. + +It installs a fully automated platform of open source cloud native tools with a simple `init` and `create` command. + +### Prerequisites + +[Install](../../../index.mdx#install-the-kubefirst-cli) the kubefirst CLI. + +#### AWS Prerequisites + +1. Create an AWS account with billing enabled. +2. Establish a public hosted zone with DNS routing established ([docs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)). +3. Connect with [Administrator Access](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AdministratorAccessserviceLevelSummary) IAM credentials to your AWS account ([docs](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)). +4. Our Homebrew package will automatically install the [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) dependency. If you use another installation method, you will need to install this utility. + +### Step 1 - Create your kbot user and a personal access token + +The kubefirst CLI will automatically create one admin user for you named `kbot`. After the installation, you will temporarily use that `kbot` account to onboard yourself and the rest your team to the platform. From that point forward, the `kbot` user should only be used for automated activities, and you should use your own personal account for everything else. + +The `kbot` user needs to be associated with a GitHub user account that can be used as your organization's bot account. Log out of GitHub and create a new GitHub account to represent this new `kbot` account. Because this account will be used for automation, it's good to choose a username that generically represents your company or your project name - something like `yourcompany-kbot`. You can also have fun with it and give your bot a fun name - the point is that this is not an account for your long term personal use, it's for the kubefirst platform system to use. + +Your new `kbot` account will need to be associated with a GitHub organization. + +- If you don't already have one that you want to use, while logged into GitHub with your new `kbot` account, establish a new [GitHub organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). +- If you do already have a GitHub organization that you want to add kubefirst to, you'll need to add your new kubefirst bot as an owner to the existing organization. + +#### GitHub ephemeral authorization during install + +If you don't export a `GITHUB_TOKEN` to your shell, the kubefirst CLI can generate an ephemeral token that last 8 hours.If you don't export a `GITHUB_TOKEN` to your shell, the kubefirst CLI can generate an ephemeral token that last 8 hours. + +### Step 2 - Create your platform + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxx + +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --domain-name your-company.io \ + --cluster-name kubefirst-mgmt \ + --github-org your-github-organization-name +``` + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/aws/github/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst aws root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +Replace `kubefirst` in the command below with your cluster's name if you specified one + +```bash +aws eks update-kubeconfig --name kubefirst +``` + +To view all cluster pods run + +```bash +kubectl get pods -A +``` \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/partials/github/_overview.mdx b/versioned_docs/version-2.2/aws/partials/github/_overview.mdx new file mode 100644 index 00000000..51a94691 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/github/_overview.mdx @@ -0,0 +1,14 @@ +Your AWS EKS cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitHub Action Runner Controller | GitHub Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Ingress Nginx | Ingress Controller | diff --git a/versioned_docs/version-2.2/aws/partials/github/_repositories.mdx b/versioned_docs/version-2.2/aws/partials/github/_repositories.mdx new file mode 100644 index 00000000..d8c234da --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/github/_repositories.mdx @@ -0,0 +1,46 @@ +# GitHub Repositories + +When you install the AWS GitHub version of kubefirst, 2 new repositories will be added to your organization's GitHub account as shown here. + +![GitHub repositories](../../../img/common/github/repositories.png) + +## Repository Summary + +### `gitops` + +The `gitops` repository houses all of our IAC and all our GitOps configurations. All of the infrastructure that you receive with kubefirst was produced by some combination of Terraform and Argo CD. You can add any infrastructure or application to your platform by pull requesting it to your new `gitops` repository. + +### metaphor + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## GitHub Repository Management + +These GitHub repositories are being managed in Terraform. + +As you need additional GitHub repositories, just add a new section of Terraform code to `terraform/github/repos.tf`: + +```terraform +# set auto_init to false if importing an existing repository +# true if it's a new repository + +module "your_repo_name" { + source = "./modules/repository" + visibility = "private" + repo_name = "your-repo-name" + archive_on_destroy = true + auto_init = false +} +``` + +GitHub's Terraform provider provides many more configuration options than just these settings. Check them out and add to your default settings once you're comfortable with the platform. + +Take a look at the `Resources` section of the GitHub provider [documentation](https://registry.terraform.io/providers/integrations/github/latest/docs). + +That was just GitHub. Take a look at all the Terraform providers that are available; the list of technologies you can manage in Terraform is really impressive. [](https://www.terraform.io/docs/providers/index.html) + +## Making Terraform Changes + +To make infrastructure and configuration changes with Terraform, simply open a pull request against any of the Terraform directory folders in the `gitops` repository. Your pull request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +![Atlantis GitHub](../../../img/common/github/atlantis.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/partials/gitlab/_cluster-create.mdx b/versioned_docs/version-2.2/aws/partials/gitlab/_cluster-create.mdx new file mode 100644 index 00000000..20d539e4 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/gitlab/_cluster-create.mdx @@ -0,0 +1,14 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitLab token in addition to the appropriate values for your new platform. + +```shell +export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxx + +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --git-provider gitlab \ + --gitlab-group your-gitlab-group \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` diff --git a/versioned_docs/version-2.2/aws/partials/gitlab/_install.mdx b/versioned_docs/version-2.2/aws/partials/gitlab/_install.mdx new file mode 100644 index 00000000..3d63766f --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/gitlab/_install.mdx @@ -0,0 +1,75 @@ +## AWS Platform Installation using GitLab + +**kubefirst** is the name of our command line tool that installs the kubefirst platform and provides some platform conveniences. + +It installs a fully automated platform of open source cloud native tools with a simple `init` and `create` command. + +![kubefirst Cluster](../../../img/aws/gitlab/installation-diagram-dark.png#dark-mode)![kubefirst Cluster](../../../img/aws/gitlab/installation-diagram-light.png#light-mode) + +### Prerequisites + +- [Install](../../../index.mdx#install-the-kubefirst-cli) the kubefirst CLI. + +#### GitLab + +- Create or use an existing [GitLab account](https://gitlab.com). +- Create a [GitLab group](https://docs.gitlab.com/ee/user/group/) developer permissions. + +> GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization. + +#### AWS + +1. Create an AWS account with billing enabled. +2. Establish a public hosted zone with DNS routing established([docs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)). +3. Connect with [Administrator Access](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AdministratorAccessserviceLevelSummary) IAM credentials to your AWS account ([docs](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)). +4. Our Homebrew package will automatically install the [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) dependency. If you use another installation method, you will need to install this utility. + +### Step 1 - Create your kbot user and a personal access token + +The kubefirst cli will automatically create one admin user for you named `kbot`. After the installation, you will temporarily use that `kbot` account to onboard yourself and the rest your team to the platform. From that point forward, the `kbot` should only be used for automated activities, and you should use your own personal account. + +The `kbot` user needs to be associated with a GitLab user account that can be used as your organization's bot account. Log out of GitLab and create a new GitLab account to represent this new `kbot` account. Because this account will be used for automation, it's a good to choose a username that generically represents your company or project name. You can also have fun with it and give your bot a fun name - the point is that this is not an account for your long term personal use, it's for the kubefirst platform system to use. + +Your new `kbot` account will need to be associated with a GitLab organization. + +- If you don't already have one that you want to use, while logged into GitLab with your new `kbot` account, establish a new [GitLab organization](https://docs.gitlab.com/ee/topics/set_up_organization.html). +- If you do already have a GitLab org that you want to add kubefirst to, you'll need to add your new kubefirst bot as an owner to the existing organization now. + +### Step 2 - Create your platform + +```shell +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --git-provider gitlab \ + --gitlab-group your-gitlab-group \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/aws/gitlab/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst aws root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +Replace `kubefirst` in the command below with your cluster's name if you specified one + +```bash +aws eks update-kubeconfig --name kubefirst +``` + +To view all cluster pods run + +```bash +kubectl get pods -A +``` \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/partials/gitlab/_overview.mdx b/versioned_docs/version-2.2/aws/partials/gitlab/_overview.mdx new file mode 100644 index 00000000..c881c171 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/gitlab/_overview.mdx @@ -0,0 +1,14 @@ +Your AWS EKS cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitLab Runner | GitLab Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Ingress Nginx | Ingress Controller | diff --git a/versioned_docs/version-2.2/aws/partials/gitlab/_repositories.mdx b/versioned_docs/version-2.2/aws/partials/gitlab/_repositories.mdx new file mode 100644 index 00000000..8e9f1ca8 --- /dev/null +++ b/versioned_docs/version-2.2/aws/partials/gitlab/_repositories.mdx @@ -0,0 +1,44 @@ +# GitLab Repositories + +In the GitOps nature, we rely on repositories to have a single source of truth when it comes to project updates. kubefirst makes heavy use of the GitOps approach to automate the development and maintenance of applications. In that regard, during the installation process, kubefirst will create a few GitLab repositories as described below. + +## Repositories + +![GitLab repositories](../../../img/common/gitlab/repositories.png) + +### `gitops` + +The `gitops` repository houses all of our IAC and all of our GitOps configurations. All of the infrastructure that you receive with kubefirst was produced by Terraform and all of your applications are delivered with Argo CD. You will add to this `gitops` repository as your business needs require additional infrastructure or applications. + +### metaphor + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## Repositories Management + +The repositories are being managed in Terraform. If you need additional repositories, just add a new section of Terraform code to `terraform/gitlab/kubefirst-repos.tf` + +```terraform +module "your_repo_name" { + depends_on = [ + gitlab_group.kubefirst + ] + source = "./templates/gitlab-repo" + group_name = gitlab_group.kubefirst.id + repo_name = "your-repo-name" + create_ecr = true + initialize_with_readme = true + only_allow_merge_if_pipeline_succeeds = false + remove_source_branch_after_merge = true +} +``` + +GitLab's Terraform provider offer many more configuration options than just these settings. Take a look at the `Resources` section of the [GitLab provider documentation](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs/resources). + +## Making Terraform Changes + +To make infrastructure and configuration changes with Terraform, simply open a merge request in the `gitops` repository. Your merge request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +All this automation is possible because of Atlantis. Atlantis is a tool that runs in your Kubernetes cluster and via a webhook, listens for merge requests in your `gitops` repository. When it detect a merge request, it will run `terraform plan`, and post the plan as a comment in the merge request. If the Terraform plan succeed, Atlantis will run `terraform apply`, and post the results as a comment in the merge request. + +![Terraform Atlantis Merge Request](../../../img/common/gitlab/atlantis.png) diff --git a/versioned_docs/version-2.2/aws/quick-start/iac-and-app-delivery.mdx b/versioned_docs/version-2.2/aws/quick-start/iac-and-app-delivery.mdx new file mode 100644 index 00000000..3e32eb3c --- /dev/null +++ b/versioned_docs/version-2.2/aws/quick-start/iac-and-app-delivery.mdx @@ -0,0 +1,36 @@ +--- +hide_title: true +sidebar_label: IAC and App Delivery +sidebar_position: 3 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: an overview of the kubefirst platform on aws elastic kubernetes service (EKS) +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +## Step 1: Console UI + +Once the aws platform has completed provisioning, the Console UI will provide you with a dashboard to navigate to some of the new services that were provisioned. + +![console UI](../../img/common/github/console.png) + +## Step 2: Add Your Team (optional while evaluating) + +See our [guide](../../common/terraform.mdx#how-can-i-use-atlantis-to-add-a-new-user-on-my-github-backed-installation) to onboard yourself and your team to the platform. + +## Step 3: Deliver Metaphor to Development, Staging, and Production + +Metaphor is our sample application that we use to demonstrate parts of the platform and to test CI changes. + +If you visit its `/.github/workflows/main.yaml` in the metaphor repository, you'll see it's just sending some workflows to Argo in your EKS cluster. Those workflows are also in the `metaphor` repository in the `.argo` directory. + +The metaphor pipeline will: + +- Publish the metaphor container to your private ECR. +- add the metaphor image to a release candidate Helm chart and publish it to ChartMuseum. +- set the metaphor with the desired Helm chart version in the `gitops` repository for development and staging. +- the release stage of the pipeline will republish the chart, this time without the release candidate notation making it an officially released version and prepare the metaphor application chart for the next release version. +- the officially released chart will be set as the desired Helm chart for production. + +To watch this pipeline occur, make any change to the `main` branch of the `metaphor` repository. If you're not feeling creative, you can just add a newline to the README.md. Once a file in `main` is changed, navigate to metaphor's CI/CD in the GitHub Actions tab to see the workflows get submitted to Argo workflows. + +You can visit the metaphor development, staging, and production apps in your browser to see the versions change and Argo CD syncs the apps. The metaphor URLs can be found in your GitOps and metaphor project `README.md` files. diff --git a/versioned_docs/version-2.2/aws/quick-start/install/cli.mdx b/versioned_docs/version-2.2/aws/quick-start/install/cli.mdx new file mode 100644 index 00000000..b750c22f --- /dev/null +++ b/versioned_docs/version-2.2/aws/quick-start/install/cli.mdx @@ -0,0 +1,69 @@ +--- +hide_title: true +sidebar_label: CLI +sidebar_position: 2 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +import GitHubClusterCreateCmd from "@site/docs/aws/partials/github/_cluster-create.mdx"; +import GitLabClusterCreateCmd from "@site/docs/aws/partials/gitlab/_cluster-create.mdx"; + +import CommonCloudPrerequisites from "@site/docs/aws/partials/common/_prerequisites.mdx"; +import CommonClusterConnectivity from "@site/docs/aws/partials/common/_cluster-connectivity.mdx"; +import CommonGitHubPrerequisites from "@site/docs/common/partials/github/_prerequisites.mdx"; +import CommonGitLabPrerequisites from "@site/docs/common/partials/gitlab/_prerequisites.mdx"; +import AWSRootCredentialsCmd from "@site/docs/aws/partials/common/_root-credentials-cmd.mdx"; +import CommonTerminalOutput from "@site/docs/common/partials/common/_terminal-output.mdx"; + +import * as config from "@site/docs/constants.js" +import styles from "@site/docs/stylesheets/tabs.module.css"; + +export const TabLabel = ({ imgSrc, label }) => ( +
+ + {label} +
+); + + + } + > + + + + + + + + + + + + + + } + > + + + + + + + + + + + + + + diff --git a/versioned_docs/version-2.2/aws/quick-start/install/ui.mdx b/versioned_docs/version-2.2/aws/quick-start/install/ui.mdx new file mode 100644 index 00000000..d6ca774f --- /dev/null +++ b/versioned_docs/version-2.2/aws/quick-start/install/ui.mdx @@ -0,0 +1,84 @@ +--- +hide_title: true +sidebar_label: Console UI +sidebar_position: 1 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +There are a few ways to install kubefirst, whether you have a cluster already or don't. + + + +# Install Kubefirst + +## Step 1: Install kubefirst console + + + +# Helm + +This will install our platform installer tools to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# Helm (ARM / M1 Mac / M2 Mac) + +This will install our platform installer UI to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +This example shows a couple additional helm values settings that enable mongo to +run on the ARM architecture. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace \ +--set=mongodb.image.repository=arm64v8/mongo \ +--set=mongodb.image.tag=latest \ +--set=mongodb.persistence.mountPath=/data/db \ +--set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ +kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# No kubernetes yet? + +**No cluster? No problem!** Let us create your bootstrap cluster for you as well. We'll install our provisioning tool into it to create your permanent infrastructure. + +``` +brew install kubefirst/tools/kubefirst + +kubefirst launch up +``` + +Then connect to the provisioning tool at +[https://console.kubefirst.dev](https://console.kubefirst.dev ) + +:::note +The kubefirst.dev domain is only available after `kubefirst launch up` and resolves to the host machine. +::: + + + +## Step 2: Install your kubefirst management cluster + +Provide details about your preferred git provider, cloud provider, access, and cluster details and let kubefirst do the rest. + +![kubefirst user interface showing cloud and git options](../../../img/console/installer.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/aws/quick-start/repositories.mdx b/versioned_docs/version-2.2/aws/quick-start/repositories.mdx new file mode 100644 index 00000000..f025ea58 --- /dev/null +++ b/versioned_docs/version-2.2/aws/quick-start/repositories.mdx @@ -0,0 +1,55 @@ +--- +hide_title: true +sidebar_label: Repositories +sidebar_position: 2 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: the git repositories created by the kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +import GitHubRepositories from '@site/docs/aws/partials/github/_repositories.mdx' +import GitLabRepositories from '@site/docs/aws/partials/gitlab/_repositories.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/aws/quick-start/styles.module.css b/versioned_docs/version-2.2/aws/quick-start/styles.module.css new file mode 100644 index 00000000..ec10699b --- /dev/null +++ b/versioned_docs/version-2.2/aws/quick-start/styles.module.css @@ -0,0 +1,13 @@ +.gitlab { +color: #fc6d26; +} +.gitlab[aria-selected='true'] { +border-bottom-color: #fc6d26; +} + +.github { +color: black; +} +.github[aria-selected='true'] { +border-bottom-color: black; +} diff --git a/versioned_docs/version-2.2/civo/credits.mdx b/versioned_docs/version-2.2/civo/credits.mdx new file mode 100644 index 00000000..2652442f --- /dev/null +++ b/versioned_docs/version-2.2/civo/credits.mdx @@ -0,0 +1,11 @@ +--- +hide_title: true +sidebar_label: Credits +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: credit to all the awesome open source projects +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import CommonCredits from "@site/docs/common/credits.mdx" + + \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/deprovision.mdx b/versioned_docs/version-2.2/civo/deprovision.mdx new file mode 100644 index 00000000..e8496975 --- /dev/null +++ b/versioned_docs/version-2.2/civo/deprovision.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: civo +sidebar_label: Deprovision +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: how to deprovision your kubefirst platform +keywords: + - aws +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Deprovision from '@site/docs/common/deprovision.mdx' + + diff --git a/versioned_docs/version-2.2/civo/explore/argocd.mdx b/versioned_docs/version-2.2/civo/explore/argocd.mdx new file mode 100644 index 00000000..9f4f59f0 --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/argocd.mdx @@ -0,0 +1,8 @@ +--- +title: Argo CD +sidebar_position: 1 +--- + +import ExploreArgocd from "@site/docs/common/argocd.mdx" + + diff --git a/versioned_docs/version-2.2/civo/explore/gitops.mdx b/versioned_docs/version-2.2/civo/explore/gitops.mdx new file mode 100644 index 00000000..b1ac43cd --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/gitops.mdx @@ -0,0 +1,9 @@ +--- +title: GitOps +sidebar_position: 2 +--- + + +import ExploreGitOps from "@site/docs/common/gitops.mdx" + + diff --git a/versioned_docs/version-2.2/civo/explore/metaphor.mdx b/versioned_docs/version-2.2/civo/explore/metaphor.mdx new file mode 100644 index 00000000..6ff78d11 --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/metaphor.mdx @@ -0,0 +1,8 @@ +--- +title: Metaphor +sidebar_position: 3 +--- + +import ExploreMetaphor from "@site/docs/common/metaphor.mdx" + + diff --git a/versioned_docs/version-2.2/civo/explore/telemetry.mdx b/versioned_docs/version-2.2/civo/explore/telemetry.mdx new file mode 100644 index 00000000..dfebeac8 --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/telemetry.mdx @@ -0,0 +1,8 @@ +--- +title: Telemetry +sidebar_position: 7 +--- + +import ExploreTelemetry from "@site/docs/common/telemetry.mdx" + + diff --git a/versioned_docs/version-2.2/civo/explore/terraform.mdx b/versioned_docs/version-2.2/civo/explore/terraform.mdx new file mode 100644 index 00000000..cfdd1f88 --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/terraform.mdx @@ -0,0 +1,8 @@ +--- +title: Terraform & Atlantis +sidebar_position: 4 +--- + +import ExploreTerraform from "@site/docs/common/terraform.mdx" + + diff --git a/versioned_docs/version-2.2/civo/explore/user-creation.mdx b/versioned_docs/version-2.2/civo/explore/user-creation.mdx new file mode 100644 index 00000000..51411716 --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/user-creation.mdx @@ -0,0 +1,37 @@ +--- +title: User Creation +sidebar_position: 5 +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; + +import GitHubUserCreation from '@site/docs/civo/partials/github/_user-creation.mdx' +import GitLabUserCreation from '@site/docs/civo/partials/gitlab/_user-creation.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/explore/vault.mdx b/versioned_docs/version-2.2/civo/explore/vault.mdx new file mode 100644 index 00000000..49695f4a --- /dev/null +++ b/versioned_docs/version-2.2/civo/explore/vault.mdx @@ -0,0 +1,8 @@ +--- +title: Vault +sidebar_position: 6 +--- + +import ExploreVault from "@site/docs/common/vault.mdx" + + diff --git a/versioned_docs/version-2.2/civo/faq.mdx b/versioned_docs/version-2.2/civo/faq.mdx new file mode 100644 index 00000000..55bb58eb --- /dev/null +++ b/versioned_docs/version-2.2/civo/faq.mdx @@ -0,0 +1,11 @@ +--- +hide_title: true +sidebar_label: FAQ +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: frequently asked quesitons about the kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import FAQ from "@site/docs/common/faq.mdx" + + diff --git a/versioned_docs/version-2.2/civo/gitops-catalog.mdx b/versioned_docs/version-2.2/civo/gitops-catalog.mdx new file mode 100644 index 00000000..b448ff3c --- /dev/null +++ b/versioned_docs/version-2.2/civo/gitops-catalog.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: civo +sidebar_label: GitOps Catalog +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: using the kubefirst gitops catalog +keywords: + - aws +image: 'https://docs.kubefirst.io/img/logo.svg' +--- + +import GitOpsCatalog from '@site/docs/common/gitops-catalog.mdx'; + + diff --git a/versioned_docs/version-2.2/civo/overview.mdx b/versioned_docs/version-2.2/civo/overview.mdx new file mode 100644 index 00000000..f3e96527 --- /dev/null +++ b/versioned_docs/version-2.2/civo/overview.mdx @@ -0,0 +1,74 @@ +--- +hide_title: true +sidebar_label: Overview +sidebar_position: 1 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: an overview of kubefirst on a civo kubernetes cluster +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + +import GitHubOverview from '@site/docs/civo/partials/github/_overview.mdx' +import GitLabOverview from '@site/docs/civo/partials/gitlab/_overview.mdx' +import CloudBanner from '@site/src/components/CloudBanner/CloudBanner.jsx' + +
+
+ +
+
+ + +# Overview + +The Civo provisioning process will: +- create a gitops git repository from our gitops-template and store it in your git provider +- create a kubernetes cluster in the Civo cloud +- install argocd bootstrapped against your gitops repo so your repo powers the platform +- install all the platform apps using gitops (gitops repo `/registry` folder) +- apply terraform to configure Vault (gitops repo `/terraform/vault` folder) +- bind a webhook to ngrok in cluster so you can automate terraform executions through atlantis +- integrate argo workflows with your git provider +- install argo workflow [cluster workflow templates](https://argoproj.github.io/argo-workflows/cluster-workflow-templates/#cluster-workflow-templates) to build containers, publish charts, and provide gitops delivery pipelines +- install a sample app git repository that uses this automation to demonstrate app delivery (metaphor repo) + +![kubefirst Civo with GitLab Cluster Diagram](../img/civo/gitlab/installation-diagram-light.png#light-mode)![kubefirst Civo with GitLab Cluster Diagram](../img/civo/gitlab/installation-diagram-dark.png#dark-mode) + +# Applications + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/civo/partials/common/_cluster-connectivity.mdx b/versioned_docs/version-2.2/civo/partials/common/_cluster-connectivity.mdx new file mode 100644 index 00000000..8ef8fac6 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/common/_cluster-connectivity.mdx @@ -0,0 +1,13 @@ +## Connecting to Kubernetes + +To connect to your new Kubernetes cluster, run + +```bash +export KUBECONFIG=~/.k1/kubeconfig +``` + +To view all cluster pods, run + +```bash +kubectl get pods -A +``` diff --git a/versioned_docs/version-2.2/civo/partials/common/_installed-applications.mdx b/versioned_docs/version-2.2/civo/partials/common/_installed-applications.mdx new file mode 100644 index 00000000..3a8283c0 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/common/_installed-applications.mdx @@ -0,0 +1,3 @@ +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../../overview.mdx). diff --git a/versioned_docs/version-2.2/civo/partials/common/_prerequisites.mdx b/versioned_docs/version-2.2/civo/partials/common/_prerequisites.mdx new file mode 100644 index 00000000..4561ea27 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/common/_prerequisites.mdx @@ -0,0 +1,26 @@ +## Prerequisites + +### Local Prerequisites + +If you are on macOS, and have [Homebrew](https://brew.sh) installed, you can run: + +```shell +brew install kubefirst/tools/kubefirst +``` + +To upgrade an existing kubefirst CLI to the latest version run: + +```shell +brew update +brew upgrade kubefirst +``` + +There are other ways to install kubefirst for different operating systems, architectures, and containerized environments. See our [installation README](https://github.com/kubefirst/kubefirst/blob/main/build/README.md) for details. + +### Civo Prerequisites + +For kubefirst to be able to provision your Civo cloud resources: + +- A [Civo account](https://dashboard.civo.com/signup) in which you are an account owner. +- A publicly routable [DNS](https://www.civo.com/learn/configure-dns#adding-a-domain-name). +- A [Civo token](https://dashboard.civo.com/security). diff --git a/versioned_docs/version-2.2/civo/partials/common/_root-credentials-cmd.mdx b/versioned_docs/version-2.2/civo/partials/common/_root-credentials-cmd.mdx new file mode 100644 index 00000000..0190df4d --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/common/_root-credentials-cmd.mdx @@ -0,0 +1,12 @@ +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst civo root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +:::note the `kubefirst civo root-credentials` command was introduced in 2.0.1 +::: diff --git a/versioned_docs/version-2.2/civo/partials/github/_cluster-create.mdx b/versioned_docs/version-2.2/civo/partials/github/_cluster-create.mdx new file mode 100644 index 00000000..92bc0f20 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_cluster-create.mdx @@ -0,0 +1,23 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Civo tokens in addition to the appropriate values for your new platform. + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx +export CIVO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +kubefirst civo create \ + --alerts-email yourdistro@your-company.io \ + --github-org your-github-org \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` + +The kubefirst cli will produce a directory of utilities, a state file, and some staged platform content that can now be found in the `~/.kubefirst` and `~/.k1` folders on your local machine. + +After the ~10 minute installation, your browser will launch a new tab to the [kubefirst Console](https://github.com/kubefirst/console), which will help you navigate your new suite of tools running in your new Civo cluster. + +If your deployment is not successful, errors and troubleshooting information will be stored in a local log file specified during the installation run. + +![terminal handoff](../../../img/civo/gitlab/handoff-screen.png) +*add console ui image for kubefirst launch diff --git a/versioned_docs/version-2.2/civo/partials/github/_install.mdx b/versioned_docs/version-2.2/civo/partials/github/_install.mdx new file mode 100644 index 00000000..1ae99d1c --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_install.mdx @@ -0,0 +1,75 @@ +# Civo Platform Installation + +kubefirst generates your cloud native platform from a `helm install` or a `kubefirst` CLI execution. + +## Prerequisites + +### GitHub Prerequisites + +- A GitHub [organisation](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). +- A new GitHub [account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) for your `kbot` automation user. +- A GitHub [personal access token](../../../common/git-auth.mdx) for your `kbot` account. + +### Civo Prerequisites + +For kubefirst to be able to provision your Civo cloud resources: + +- A [Civo account](https://dashboard.civo.com/signup) in which you are an account owner. +- A publicly routable [DNS](https://www.civo.com/learn/configure-dns#adding-a-domain-name). +- A [Civo token](https://dashboard.civo.com/security). + +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Civo tokens in addition to the appropriate values for your new platform. + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx +export CIVO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +kubefirst civo create \ + --alerts-email yourdistro@your-company.io \ + --github-org your-github-org \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` + +The kubefirst cli will produce a directory of utilities, a state file, and some staged platform content that can now be found in the `~/.kubefirst` and `~/.k1` folders on your local machine. + +After the ~10 minute installation, your browser will launch a new tab to the [kubefirst Console](https://github.com/kubefirst/console), which will help you navigate your new suite of tools running in your new Civo cluster. + +If your deployment is not successful, errors and troubleshooting information will be stored in a local log file specified during the installation run. + +## Console UI Screen + +![kubefirst console screen](../../../img/common/github/console.png) + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/civo/github/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst civo root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +To connect to your new Kubernetes cluster, run + +```bash +export KUBECONFIG=~/.k1/kubeconfig +``` + +To view all cluster pods, run + +```bash +kubectl get pods -A +``` + +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../../overview.mdx). \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/partials/github/_overview.mdx b/versioned_docs/version-2.2/civo/partials/github/_overview.mdx new file mode 100644 index 00000000..2243af3c --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst civo create` provisions a local [Civo](https://civo.com) Kubernetes cluster to host your cloud native environment locally. + +Your Civo cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitHub Action Runner Controller | GitHub Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Ingress Nginx | Ingress Controller | diff --git a/versioned_docs/version-2.2/civo/partials/github/_prerequisites.mdx b/versioned_docs/version-2.2/civo/partials/github/_prerequisites.mdx new file mode 100644 index 00000000..7f17b2e0 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_prerequisites.mdx @@ -0,0 +1,5 @@ +### GitHub Prerequisites + +- A GitHub [organisation](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). +- A new GitHub [account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) for your `kbot` automation user. +- A GitHub [personal access token](../../../common/git-auth.mdx) for your `kbot` account. \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/partials/github/_repositories.mdx b/versioned_docs/version-2.2/civo/partials/github/_repositories.mdx new file mode 100644 index 00000000..83a871b9 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_repositories.mdx @@ -0,0 +1,25 @@ +# GitHub Repositories + +When you deploy a cluster on Civo using kubefirst, new repositories will be added to your organization's GitHub account. + +![GitHub repositories](../../../img/common/github/repositories.png) + +## Repositories + +### gitops + +The `gitops` repository houses all of our IAC and all your GitOps configurations. The infrastructure created by kubefirst was produced by some combination of Terraform and Argo CD. You modify the infrastructure or add new applications to your cluster by creating a pull request to your new `gitops` repository. + +### metaphor + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## Repositories Management + +These {props.name} repositories are being managed in Terraform. As you need additional GitHub repositories, just add a new section of Terraform code to `civo-github/terraform/github/repos.tf`: + +## Making Terraform Changes + +To make infrastructure and configuration changes with Terraform, simply open a pull request against any of the Terraform directory folders in the `gitops` repository. Your pull request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +![Atlantis GitHub](../../../img/common/github/atlantis.png) diff --git a/versioned_docs/version-2.2/civo/partials/github/_user-creation.mdx b/versioned_docs/version-2.2/civo/partials/github/_user-creation.mdx new file mode 100644 index 00000000..4f073349 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/github/_user-creation.mdx @@ -0,0 +1,62 @@ +## Platform User Onboarding + +In this tutorial we will show how to add users to your platform through [Atlantis](https://www.runatlantis.io/), which will allow a preview of how changes made will be expressed through Terraform before branches are merged into your repository. + +Navigate to the `gitops` repository in your GitHub org, clone the contents, and create a new branch: + +```shell +cd gitops +git checkout -b new-user +``` + +The folder `civo-github/terraform/users/admins` contains two separate files that represent admin users: `admin-one.tf` (commented-out), and the kbot user in the `kbot.tf` file. Here's the module from `admin-one.tf`: + +```terraform +module "admin_one" { + source = "./modules/user/github" + + acl_policies = ["admin"] + email = "your.admin@your-company.io" + first_name = "Admin" + github_username = "admin-one-github-username" + last_name = "One" + team_id = data.github_team.admins.id + username = "aone" + user_disabled = false + userpass_accessor = data.vault_auth_backend.userpass.accessor +} +``` + +Uncomment and edit this code to replace the values for the `email`, `first_name`, `github_username`, `last_name`, and `username` before pushing to your branch. + +Note: If you are doing using this walkthrough simply to test Atlantis, you do not need to update these fields to be accurate. + +```shell +git add . +git commit -m feat: add new user +git push --set-upstream origin new-user +``` + +Create a pull request. This will kick off the Atlantis workflow. Within a minute or so of submitting the pull request, a comment will appear on the pull request that shows the Terraform plan with the changes it will be making to your infrastructure. + +![Atlantis Plan Comment Example](../../../img/common/github/atlantis-comments.png) + +To apply these changes, you or someone in the organization can submit a comment on that pull request with the following comment text: + +`atlantis apply` + +Doing so will instruct Atlantis to apply the plan. It will report back with the results of the apply within a minute or so. + +NOTE: Atlantis merges your pull request automatically once an apply is successfully executed. Don't merge Terraform pull requests yourself. + +Atlantis will always run plans automatically for you when a pull request is opened that changes files mapped in `atlantis.yaml`. + +Any new users you have created through this process will have their temporary initial passwords stored in your Vault cluster. You can access Vault using the root login credentials provided to you during your kubefirst installation. Only the root Vault token can access these secrets. You will find your users' initial passwords in the Vault secret store `/secrets/users/`. + +![vault token login](../../../img/kubefirst/local/vault-token-login.png) + +Once you've provided them their initial password, they can update their own password throughout the platform by updating their user password entity in Vault. Anyone can change their own password, and Admins can reset anyone's password. These rules, just like everything else on kubefirst, can be configured in your new `gitops` repository. + +![default user creation](../../../img/kubefirst/local/default-user-creation.png) + +The admins and developers that you add through IaC will automatically propagate to all tools due to the Vault OIDC provider that's preconfigured throughout the kubefirst platform tools. \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_cluster-create.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_cluster-create.mdx new file mode 100644 index 00000000..27ec226b --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_cluster-create.mdx @@ -0,0 +1,15 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Civo tokens in addition to the appropriate values for your new platform. + +```shell +export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx +export CIVO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +kubefirst civo create \ + --alerts-email yourdistro@your-company.io \ + --git-provider gitlab \ + --gitlab-group your-gitlab-group \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_install.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_install.mdx new file mode 100644 index 00000000..3fd2888a --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_install.mdx @@ -0,0 +1,80 @@ +# Civo Platform Installation + +kubefirst is the name of our CLI that installs the platform of the same name to your local or cloud environment. + +## Prerequisites + +[Install](../../../index.mdx#install-the-kubefirst-cli) the kubefirst CLI. + +### GitLab + +- Create or use an existing [GitLab account](https://gitlab.com). +- Create a [GitLab group](https://docs.gitlab.com/ee/user/group/) developer permissions. + +> GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization. + +### Civo + +For kubefirst to be able to provision your Civo cloud resources: + +- A [Civo account](https://dashboard.civo.com/signup) in which you are an account owner. +- A publicly routable [DNS](https://www.civo.com/learn/configure-dns#adding-a-domain-name). +- A [Civo token](https://dashboard.civo.com/security). + +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Civo tokens in addition to the appropriate values for your new platform. + +```shell +export GITLAB_TOKEN=xxxxxxxxxxxxxxxx +export CIVO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +kubefirst civo create \ + --alerts-email yourdistro@your-company.io \ + --git-provider gitlab \ + --gitlab-group your-gitlab-group \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` + +The kubefirst cli will produce a directory of utilities, a state file, and some staged platform content that can now be found in the `~/.kubefirst` and `~/.k1` folders on your local machine. + +After the ~10 minute installation, your browser will launch a new tab to the [kubefirst Console](https://github.com/kubefirst/console), which will help you navigate your new suite of tools running in your new Civo cluster. + +If your deployment is not successful, errors and troubleshooting information will be stored in a local log file specified during the installation run. + +## Console UI Screen + +![kubefirst console screen](../../../img/common/gitlab/console.png) + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/civo/gitlab/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst civo root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +To connect to your new Kubernetes cluster, run + +```bash +export KUBECONFIG=~/.k1/kubeconfig +``` + +To view all cluster pods, run + +```bash +kubectl get pods -A +``` + +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../../overview.mdx). \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_overview.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_overview.mdx new file mode 100644 index 00000000..2fcfec4b --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst civo create` provisions a local [Civo](https://civo.com) Kubernetes cluster to host your cloud native environment locally. + +Your Civo cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitLab Runner | GitLab Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Ingress Nginx | Ingress Controller | diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_prerequisites.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_prerequisites.mdx new file mode 100644 index 00000000..63993ae3 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_prerequisites.mdx @@ -0,0 +1,7 @@ +### GitLab + +- Create or use an existing [GitLab account](https://gitlab.com). +- Create a [GitLab group](https://docs.gitlab.com/ee/user/group/) developer permissions. + +:::note GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization. +::: \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_repositories.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_repositories.mdx new file mode 100644 index 00000000..6d6bc602 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_repositories.mdx @@ -0,0 +1,37 @@ +# GitLab Repositories + +When you install the Civo version of kubefirst, 2 new repositories will be added to your GitLab project as shown here. + +![GitLab repositories](../../../img/common/gitlab/repositories.png) + +## Repository Summary + +### gitops + +The GitOps repo houses all of our IAC and all our GitOps configurations. All of the infrastructure that you receive with Kubefirst was produced by some combination of Terraform and ArgoCD. You can add any infrastructure or application to your platform by pull requesting it to your new `gitops` repository. + +### metaphor + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## GitLab Repository Management + +These GitLab projects (repositories) are being managed in Terraform. As you need additional GitLab projects, just add a new section of Terraform code to `civo-gitlab/terraform/gitlab/projects.tf`: + +```terraform +module "your_repo_name" { + source = "./modules/project" + group_name = data.gitlab_group.owner.id + project_name = "your_repo_name" + # create_ecr = true + initialize_with_readme = false + only_allow_merge_if_pipeline_succeeds = false + remove_source_branch_after_merge = true +} +``` + +## Making Terraform Changes + +To make infrastructure and configuration changes with Terraform, simply open a pull request against any of the Terraform directory folders in the `gitops` repository. Your pull request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +![Atlantis GitLab](../../../img/common/gitlab/atlantis.png) diff --git a/versioned_docs/version-2.2/civo/partials/gitlab/_user-creation.mdx b/versioned_docs/version-2.2/civo/partials/gitlab/_user-creation.mdx new file mode 100644 index 00000000..cf653454 --- /dev/null +++ b/versioned_docs/version-2.2/civo/partials/gitlab/_user-creation.mdx @@ -0,0 +1,63 @@ +## Platform User Onboarding + +In this tutorial we will show how to add users to your platform through [Atlantis](https://www.runatlantis.io/), which will allow a preview of how changes made will be expressed through Terraform before branches are merged into your repository. + +Navigate to the `gitops` repository in your GitLab group, clone the contents, and create a new branch: + +```shell +cd gitops +git checkout -b new-user +``` + +The folder `civo-gitlab/terraform/users/admins` contains two separate files that represent admin users: `admin-one.tf` (commented-out), and the kbot user in the `kbot.tf` file. Here's the module from `admin-one.tf`: + +```terraform +module "admin_one" { + source = "../modules/user" + + acl_policies = ["admin"] + email = "your.admin@your-company.io" + first_name = "Admin" + fullname = "Admin One" + group_id = data.vault_identity_group.admins.group_id + gitlab_username = "your-admins-gitlab-username" + last_name = "One" + username = "aone" + user_disabled = false + userpass_accessor = data.vault_auth_backend.userpass.accessor +} +``` + +Uncomment and edit this code to replace the values for the `email`, `first_name`, `gitlab_username`, `last_name`, and `username` before pushing to your branch. + +Note: If you are doing using this walkthrough simply to test Atlantis, you do not need to update these fields to be accurate. + +```shell +git add . +git commit -m feat: add new user +git push --set-upstream origin new-user +``` + +Create a merge request. This will kick off the Atlantis workflow. Within a minute or so of submitting the merge request, a comment will appear on the merge request that shows the Terraform plan with the changes it will be making to your infrastructure. + +![Atlantis Plan Comment Example](../../../img/common/gitlab/atlantis-comments.png) + +To apply these changes, you or someone in the organization can submit a comment on that merge request with the following comment text: + +`atlantis apply` + +Doing so will instruct Atlantis to apply the plan. It will report back with the results of the apply within a minute or so. + +NOTE: Atlantis merges your merge request automatically once an apply is successfully executed. Don't merge Terraform merge requests yourself. + +Atlantis will always run plans automatically for you when a merge request is opened that changes files mapped in `atlantis.yaml`. + +Any new users you have created through this process will have their temporary initial passwords stored in your Vault cluster. You can access Vault using the root login credentials provided to you during your kubefirst installation. Only the root Vault token can access these secrets. You will find your users' initial passwords in the Vault secret store `/secrets/users/`. + +![vault token login](../../../img/kubefirst/local/vault-token-login.png) + +Once you've provided them their initial password, they can update their own password throughout the platform by updating their user password entity in Vault. Anyone can change their own password, and Admins can reset anyone's password. These rules, just like everything else on kubefirst, can be configured in your new `gitops` repository. + +![default user creation](../../../img/kubefirst/local/default-user-creation.png) + +The admins and developers that you add through IaC will automatically propagate to all tools due to the Vault OIDC provider that's preconfigured throughout the kubefirst platform tools. \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/platform.mdx b/versioned_docs/version-2.2/civo/platform.mdx new file mode 100644 index 00000000..3a2f232d --- /dev/null +++ b/versioned_docs/version-2.2/civo/platform.mdx @@ -0,0 +1,10 @@ +--- +hide_title: true +sidebar_label: kubefirst Platform +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: an overview of kubefirst +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Platform from "@site/docs/common/platform.mdx" + + \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/quick-start/install/cli.mdx b/versioned_docs/version-2.2/civo/quick-start/install/cli.mdx new file mode 100644 index 00000000..5a8fe685 --- /dev/null +++ b/versioned_docs/version-2.2/civo/quick-start/install/cli.mdx @@ -0,0 +1,65 @@ +--- +hide_title: true +sidebar_label: CLI +sidebar_position: 2 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +import GitHubPrerequisites from "@site/docs/common/partials/github/_prerequisites.mdx"; +import GitHubClusterCreateCmd from "@site/docs/civo/partials/github/_cluster-create.mdx"; + +import GitLabPrerequisites from "@site/docs/common/partials/gitlab/_prerequisites.mdx"; +import GitLabClusterCreateCmd from "@site/docs/civo/partials/gitlab/_cluster-create.mdx"; + +import CommonCloudPrerequisites from "@site/docs/civo/partials/common/_prerequisites.mdx"; +import CommonClusterConnectivity from "@site/docs/civo/partials/common/_cluster-connectivity.mdx"; +import CommonRootCredentialsCmd from "@site/docs/civo/partials/common/_root-credentials-cmd.mdx"; + +import * as config from "@site/docs/constants.js" +import styles from "@site/docs/stylesheets/tabs.module.css"; + +export const TabLabel = ({ imgSrc, label }) => ( +
+ + {label} +
+); + + + } + > + + + + + + + + + + + + } + > + + + + + + + + + + + + diff --git a/versioned_docs/version-2.2/civo/quick-start/install/ui.mdx b/versioned_docs/version-2.2/civo/quick-start/install/ui.mdx new file mode 100644 index 00000000..d6ca774f --- /dev/null +++ b/versioned_docs/version-2.2/civo/quick-start/install/ui.mdx @@ -0,0 +1,84 @@ +--- +hide_title: true +sidebar_label: Console UI +sidebar_position: 1 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +There are a few ways to install kubefirst, whether you have a cluster already or don't. + + + +# Install Kubefirst + +## Step 1: Install kubefirst console + + + +# Helm + +This will install our platform installer tools to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# Helm (ARM / M1 Mac / M2 Mac) + +This will install our platform installer UI to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +This example shows a couple additional helm values settings that enable mongo to +run on the ARM architecture. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace \ +--set=mongodb.image.repository=arm64v8/mongo \ +--set=mongodb.image.tag=latest \ +--set=mongodb.persistence.mountPath=/data/db \ +--set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ +kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# No kubernetes yet? + +**No cluster? No problem!** Let us create your bootstrap cluster for you as well. We'll install our provisioning tool into it to create your permanent infrastructure. + +``` +brew install kubefirst/tools/kubefirst + +kubefirst launch up +``` + +Then connect to the provisioning tool at +[https://console.kubefirst.dev](https://console.kubefirst.dev ) + +:::note +The kubefirst.dev domain is only available after `kubefirst launch up` and resolves to the host machine. +::: + + + +## Step 2: Install your kubefirst management cluster + +Provide details about your preferred git provider, cloud provider, access, and cluster details and let kubefirst do the rest. + +![kubefirst user interface showing cloud and git options](../../../img/console/installer.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/civo/quick-start/repositories.mdx b/versioned_docs/version-2.2/civo/quick-start/repositories.mdx new file mode 100644 index 00000000..99809eb8 --- /dev/null +++ b/versioned_docs/version-2.2/civo/quick-start/repositories.mdx @@ -0,0 +1,54 @@ +--- +hide_title: true +sidebar_label: Repositories +sidebar_position: 3 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: the installation process for kubefirst cli +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" +import GitHubRepositories from '@site/docs/civo/partials/github/_repositories.mdx' +import GitLabRepositories from '@site/docs/civo/partials/gitlab/_repositories.mdx' + +
+
+ +
+
+ + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/civo/quick-start/styles.module.css b/versioned_docs/version-2.2/civo/quick-start/styles.module.css new file mode 100644 index 00000000..ec10699b --- /dev/null +++ b/versioned_docs/version-2.2/civo/quick-start/styles.module.css @@ -0,0 +1,13 @@ +.gitlab { +color: #fc6d26; +} +.gitlab[aria-selected='true'] { +border-bottom-color: #fc6d26; +} + +.github { +color: black; +} +.github[aria-selected='true'] { +border-bottom-color: black; +} diff --git a/versioned_docs/version-2.2/common/argocd.mdx b/versioned_docs/version-2.2/common/argocd.mdx new file mode 100644 index 00000000..97945142 --- /dev/null +++ b/versioned_docs/version-2.2/common/argocd.mdx @@ -0,0 +1,29 @@ +Argo CD is a GitOps continuous delivery tool for Kubernetes. We use it to manage all of our applications across our Kubernetes clusters. + +Argo CD is really great at providing a straightforward mechanism for you to manage Helm charts, their versions, their configuration overrides, and whether their state is in sync with what is running on your clusters. + +![Argo CD Applications](../img/kubefirst/argocd/argocd-apps.png) + +## Managing Apps in Argo CD + +The configuration for all of your apps in your Kubernetes cluster can be found in your new `gitops` repository at path `/registry/`. + +GitLab registry applications: +![GitLab Applications Registry](../img/kubefirst/gitops/registry.png) + +GitHub registry applications: +![GitHub Applications Registry](../img/kubefirst/local/gitops-registry.png) + +Each of these YAML files will include details regarding the application's source, destination, and Helm configuration overrides. + +## Applying Changes in Argo CD + +Once you change the desired state of the app in the `gitops` repository `main` branch, the registered app-of-apps will sync, and any apps in Kubernetes that need adjustment will automatically sync with the state that's in git. + +## Adding Applications to Argo CD + +The registry of our Argo CD apps are all in the `/registry` root directory. Any application added here will be added to Argo CD. An app can also be an app-of-apps if you require multiple components to be delivered as a suite. You'll see plenty of examples to follow in the `/registry` directory. + +## External Docs + +Argo CD [documentation](https://argo-cd.readthedocs.io/en/stable/) diff --git a/versioned_docs/version-2.2/common/credits.mdx b/versioned_docs/version-2.2/common/credits.mdx new file mode 100644 index 00000000..ecf6a8d9 --- /dev/null +++ b/versioned_docs/version-2.2/common/credits.mdx @@ -0,0 +1,33 @@ +## The Open Source Tools We Love + +The kubefirst platform uses some of the most popular open source projects in the world. This page is dedicated to giving those projects credit for their incredible offerings, and to provide you with helpful links to their documentation. + +|Project |AWS + GitHub|AWS + GitLab|Civo + GitHub|Civo + GitLab|Local + GitHub|Local + GitLab| +|:--|:--:|:--:|:--:|:--:|:--:|:--:| +|[Argo CD](https://argoproj.github.io/cd)|X|X|X|X|X|X| +|[Argo Workflows](https://argoproj.github.io/workflows)|X|X|X|X|X|X| +|[cert-manager](https://cert-manager.io/docs)|X|X|X|X| | | +|[ChartMuseum](https://chartmuseum.com/docs)|X|X|X|X|X|X| +|[Docker](https://docker.com)| | | | |X|X| +|[GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions)|X| |X| |X| | +|[GitHub Actions Runner Controller](https://hub.docker.com/r/summerwind/actions-runner)|X| |X| |X| | +|[GitLab Runner](https://docs.gitlab.com/runner)| |X| |X| |X| +|[HashiCorp Vault](https://www.vaultproject.io)|X|X|X|X|X|X| +|[Ingress NGINX Controller](https://kubernetes.github.io/ingress-nginx)|X|X|X|X| | | +|[k3d](https://k3d.io)| | | | |X|X| +|[Kubernetes](https://kubernetes.io)|X|X|X|X|X|X| +|[Kubernetes ExternalDNS](https://github.com/kubernetes-sigs/external-dns)|X|X|X|X| | | +|[Kubernetes External Secrets Operator](https://external-secrets.io)|X|X|X|X|X|X| +|[MinIO](https://min.io/product/kubernetes)| | | | |X|X| +|[mkcert](https://github.com/FiloSottile/mkcert)| | | | |X|X| +|[ngrok](https://ngrok.com)| | | | |X|X| +|[Terraform](https://www.terraform.io)|X|X|X|X|X|X| +|[Terraform Atlantis](https://www.runatlantis.io)|X|X|X|X|X|X| +|[Traefik](https://github.com/traefik/traefik)| | | | |X|X| + +### Additional References + +- HashiCorp Vault: [training](https://learn.hashicorp.com/vault). +- Ingress NGINX Controller: [available annotations](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/). +- Kubernetes: [training](https://kubernetes.io/training/). +- Terraform: [docs](https://www.terraform.io/docs/index.html) and [training](https://learn.hashicorp.com/terraform). diff --git a/versioned_docs/version-2.2/common/deprovision.mdx b/versioned_docs/version-2.2/common/deprovision.mdx new file mode 100644 index 00000000..7eb704fc --- /dev/null +++ b/versioned_docs/version-2.2/common/deprovision.mdx @@ -0,0 +1,150 @@ +To destroy your kubefirst cluster, complete the following steps. + +## Prerequisites + +You will need to [install](http://localhost:3000/overview.md#install-the-kubefirst-cli) the `kubefirst` CLI if it is not already installed. + +Before continuing, use the command-line tool for the chosen cloud provider to get the `kubeconfig` for your cluster: + + + +# AWS + +```shell +aws eks update-kubeconfig --name my-cluster --region us-east-1 +``` + +# Civo + +```shell +civo kubernetes config my-cluster +``` + + + +If the command-line tool for the chosen cloud provider is not installed, consult the following documentation for install steps: + + + +# AWS + +https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +# Civo + +https://www.civo.com/docs/overview/civo-cli + + + +You will also need to [install](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) `terraform`. + +## Steps + +Once you have the `kubeconfig` file for your cluster, retrieve the Vault token: + +```bash +kubectl -n vault get secrets/vault-unseal-secret --template='{{index .data "root-token"}}' | base64 -d +``` + +This assumes you've exported the environment variable `KUBECONFIG=/path/to/my/kubeconfig` - if not, you can add `--kubeconfig /path/to/my/kubeconfig` just after `kubectl`. + +Once you have the Vault root token, run the following `kubefirst` command to retrieve the required environment variables for deprovisioning: + +```bash +kubefirst terraform set-env \ + --vault-token hvs... \ + --vault-url https://vault.mydomain.com \ + --output-file /some/path/.env +``` + +This will collect the required variables from the necessary secret path and output them to a file referenced by the `--output-file` flag - this will be the current directory at `.env` if no option is provided. You may override this path to whichever destination makes the most sense to you. + +Once the file generated by the previous command is available to you, you may export the variables to your `bash` session by running the following command: + +```bash +source /some/path/.env +``` + +Next, you will need to clone the `gitops` repository generated by Kubefirst during the initial cluster creation: + +```bash +git clone git@gitlab.com:my-group/gitops.git +``` + +### Terraform + +:::danger +If you have added custom resources to the `terraform` section of your gitops repository, these resources _will_ show up in the plan. Please exercise caution when destroying. +::: + +:::caution +The use of `terraform` is outside of the scope of this documentation. Please consult the official [documentation](https://developer.hashicorp.com/terraform/cli/commands/destroy) before proceeding. +::: + +Switch to the `terraform` directory inside of the cloned gitops repository. For example: + +```bash +cd gitops/terraform +``` + +Within the `terraform` directory, there are several subdirectories that contain the infrastructure-as-code declarations for your Kubefirst resources. + +#### Cloud Provider + +To deprovision the cloud provider resources, switch to the cloud provider subdirectory - for example: + +```bash +cd civo +``` + +You can then use standard `terraform` commands: + +```bash +terraform init +terraform destroy +``` + +#### Git + +To deprovision the git provider resources, switch to the git provider subdirectory - for example: + +```bash +cd gitops/git +``` + +You can then use standard `terraform` commands: + +```bash +terraform init +terraform destroy +``` + +Once you've destroyed `terraform` resources for the cloud and git providers, the only resource left to clean up is the state storage objects that Kubefirst created on your behalf. If you'd like to remove these, this can be achieved by using the cloud console or the command-line utility for your chosen cloud provider. + +## k3d + + + +## k3d + +```shell +kubefirst k3d destroy +``` + + + +The command will also delete everything added to your GitHub or GitLab account, while cleaning local files related to your deployment. + +## reset (optional) + +You can use the `kubefirst reset` command to clean local files generated by the installer while leaving the logs file, and the [SSL certificates that you backed up](../aws/advanced/certificates.mdx#backup-and-restore-certificates) untouched. This command will not destroy your cluster (cloud resources or k3d), and is not a replacement for the `destroy` command. + +## Local only + +### Removing CA from the trusted store + +If you [installed the mkcert CA (Certificate Authority) to your trusted store,](../k3d/quick-start/install.mdx#install-the-ca-certificate-authority-of-mkcert-in-your-trusted-store) you can remove it with: + +```shell +mkcert -uninstall +``` diff --git a/versioned_docs/version-2.2/common/faq.mdx b/versioned_docs/version-2.2/common/faq.mdx new file mode 100644 index 00000000..69e0ccca --- /dev/null +++ b/versioned_docs/version-2.2/common/faq.mdx @@ -0,0 +1,63 @@ +## General + +### I ran into an issue, what should I do? + +If an error occurs, try to run the command again: there is a `~/.kubefirst` file on your localhost that keeps track of your execution state. If it still doesn't work, check the log file which was created in the `~/.k1/logs` folder. + +If you are not sure about the steps to take to fix the problem you encounter, join our [Slack community](https://kubefirst.io/slack), and ask for help in the `#helping-hands` channel. We'll gladly work through it with you. + +If you think there is a bug, you can also open an [issue](https://github.com/kubefirst/kubefirst/issues) describing the problems you are having. + +### How do I tear my cluster down? + +You can easily take your cluster down, by using the [destroy command](./deprovision.mdx). + +### I'm experiencing timeouts when kubefirst deploys Argo CD or HashiCorp Vault through the Helm installations + +You may need a more stable connection / higher download speed. Check with your internet provider or use an online speed test to confirm you have at least 100mbps download speed, or else you may experience timeouts. + +### Where can I find the services passwords? + +Run the command `kubefirst root-credentials` where `` is one of `k3d`, `aws`, `civo` + +### I'm stuck with artifacts after a failed local installation and can't continue + +If you still cannot complete the installation due to remaining artifacts after completing a `kubefirst k3d destroy`, you may have to do a manual teardown. Firstly, you need to delete the k3d cluster with the following command: + +```shell +$HOME/.k1/tools/k3d cluster delete kubefirst +kubefirst reset +``` + +Once it's done, you can delete the GitHub assets we created by logging into your account and removing the `gitops`, and `metaphor` repositories. You can also use the GitHub CLI to do that1: + +```shell +gh repo delete /metaphor --confirm +gh repo delete /gitops --confirm +``` + +## Civo + +### Dummy website served at your domain root + + + +With Civo, Google Search Crawlers are flagging domains as deceptive when they have no apex records. It is a problem happening only with Civo: you won't have this issue with AWS or local (k3d) deployment. To fix the issue, we added an apex record, and created a pod with a NGINX server at the domain root, delivering a dummy website. + +If you want to replace the dummy website with yours or serve an application instead, it should still prevent the problem from happening. If removed, you may see the following error when accessing your domain (or any of its subdomains) in the browser. + +![Deceptive Browser Warning](../img/civo/deceptive-warning.png) + +## Local (k3d) + +### Cannot connect to the Docker daemon + +```shell +Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? +``` + +If Docker is running, and working properly (run `docker run hello-world` in your terminal to test it), but you get the error above while trying to create a cluster with k3d, it may be related to [this Docker issue](https://github.com/docker/for-mac/issues/6529). It was fixed a while ago, but it seems like the problem is back. Since it's a Docker issue, and that the Unix sockets default path should be `/var/run/docker.sock`, you can specify the path using the `DOCKER_HOST` variable: + +```shell +export DOCKER_HOST="unix://$HOME/.docker/run/docker.sock" +``` \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/git-auth.mdx b/versioned_docs/version-2.2/common/git-auth.mdx new file mode 100644 index 00000000..e9465c33 --- /dev/null +++ b/versioned_docs/version-2.2/common/git-auth.mdx @@ -0,0 +1,52 @@ +--- +title: Git Authentication +id: gitAuth +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; + +import GitHubTokens from '@site/docs/common/partials/github/_tokens.mdx' +import GitLabTokens from '@site/docs/common/partials/gitlab/_tokens.mdx' + +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/common/gitops-catalog.mdx b/versioned_docs/version-2.2/common/gitops-catalog.mdx new file mode 100644 index 00000000..a38fc216 --- /dev/null +++ b/versioned_docs/version-2.2/common/gitops-catalog.mdx @@ -0,0 +1,83 @@ +# GitOps Catalog + +After your kubefirst cluster has been provisioned, you can optionally leverage the Kubefirst GitOps Catalog. + +The GitOps Catalog is a curated collection of Kubernetes applications that can be deployed directly to your kubefirst cluster(s). + +For more information regarding applications that are generally available, check out the GitOps Catalog [repository](https://github.com/kubefirst/gitops-catalog). + +## Using the catalog + +After your cluster has been provisioned, you're able to click on a button to **open kubefirst console**: + +![Cluster provision complete](../img/common/catalog/button.png) + +Once this button has been clicked, you're presented with the **Services Overview** page: + +![Services Overview page](../img/common/catalog/page.png) + +This page shows the services that have been provisioned to your kubefirst management cluster. Default applications will show up in this list as well. + +You can click on the **GitOps catalog** button to show the catalog: + +![GitOps catalog](../img/common/catalog/services.png) + +From here, you can click **Install** on any of the available services to deploy them to your cluster. + +## How this works + +When you opt to install any of the available services from the GitOps Catalog, the kubefirst API formats and commits a set of files to your gitops repository. + +Then, Argo CD is asked to refresh the upstream registry to synchronize the newly deployed application. + +Since the deployment of these applications is done directly in your gitops repository, you have full ownership to then customize these applications by adjusting their content within your gitops repository. + +For example - consider the following sample deployment of Kuberntes Dashboard: + +```yaml +--- +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: kubernetes-dashboard + namespace: argocd +spec: + project: default + source: + repoURL: 'https://kubernetes.github.io/dashboard' + targetRevision: 6.0.0 + chart: kubernetes-dashboard + destination: + server: 'https://kubernetes.default.svc' + namespace: kubernetes-dashboard + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true + +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: k8s-dashboard-clusterrole + annotations: + argocd.argoproj.io/sync-wave: '0' +subjects: + - kind: ServiceAccount + name: k8s-dashboard-sa + namespace: default +roleRef: + kind: ClusterRole + name: admin + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: k8s-dashboard-sa + namespace: default +``` + +If you'd like to change any of the helm chart values, change the helm chart version, or add any additional resources, you simply edit this file and Argo CD will detect the changes from your upstream gitops repository and synchronize. diff --git a/versioned_docs/version-2.2/common/gitops.mdx b/versioned_docs/version-2.2/common/gitops.mdx new file mode 100644 index 00000000..8fda2f63 --- /dev/null +++ b/versioned_docs/version-2.2/common/gitops.mdx @@ -0,0 +1,69 @@ +# kubefirst GitOps CI/CD + +The days of scripting `kubectl apply` and `helm install` in your operations are over. The kubefirst platform comes with all the tools you need to run a scalable GitOps platform powered by Argo CD GitOps. + +![GitOps Flow](../img/gitops/gitops-diagram-light.png#light-mode)![GitOps Flow](../img/gitops/gitops-diagram-dark.png#dark-mode) + +## The Benefits of GitOps + +The benefit of defining your desired state in a declarative way in Git is enormous. + +- An audit log of every system change including who made and who approved the change is available. +- A secure main branch of the GitOps repository makes for very easy security and approval controls for system changes. +- Easy to understand rollbacks (just revert the Git commit that caused the problem and you'll be on the last version). +- The declarative state in Git significantly reduces the complexity of disaster recovery. +- Creating new environments is as straight-forward as duplicating directory structures. +- Having everything declared in the GitOps repository means everyone can agree to the source of truth for every version of every app. + +## Pipelines + +![GitOps CI/CD Pipelines](../img/gitops/gitops-pipelines-light.png#light-mode)![GitOps CI/CD Pipelines](../img/gitops/gitops-pipelines-dark.png#dark-mode) + +Our CI pipelines originate in your privately hosted git repository trigger mechanism (GitHub Actions or GitLab CI) with a workflow being submitted to Argo Workflows. The workflows will publish your container with a pre-release Helm chart. + +The pipelines then continue with promotion of the release through the `preprod` environments. + +Once the release is ready, the release chart is published and delivered to production, and the application chart's version will be prepared for the next release. + +### GitHub Integration with Argo Workflows + +![Argo Workflows with GitHub](../img/kubefirst/github/github-argo-workflow.png) + +The integration that we've established between GitHub and Argo Workflows will surface your powerful Argo Workflows engine directly in GitHub Actions, so that your developers have all of the workflow execution information available, directly associated with their commit in their application repository. + +### GitLab Integration with Argo Workflows + +![Argo Workflows Integration with GitLab](../img/kubefirst/gitops/gitlab-workflows-integration.png) + +The integration that we've established between GitLab and Argo Workflows will surface your powerful Argo Workflows engine directly in GitLab's native CI, so that your developers have all of the workflow execution information available directly associated with their commit in their application repository. + +![Argo Workflows with GitLab](../img/kubefirst/gitlab/gitlab-argo-workflow.png) + +## GitOps Resources + +Our registry includes GitOps patterns for numerous source types including: + +- Helm Charts +- Wrapper Charts +- Kubernetes Manifest Files + +The metaphor example application includes an example of how easy it is to set different configuration overrides for your different environments. + +To see what it takes to make the `development` instance of `metaphor` different than the others, visit the `gitops` repository and navigate to `/components/development/metaphor/values.yaml` + +Any Helm value that should deviate from the default chart can be set here so your environment overrides are always concise and clear. + +## Using Your Own `gitops-template` Repository Fork + +If you want to customize the template before creating a new cluster, you can fork the [`gitops-template` repository](https://github.com/kubefirst/gitops-template), and use it as the source for cluster creation. To do so, follow the [forking instructions from GitHub](https://docs.github.com/en/get-started/quickstart/fork-a-repo). Note that the tags won't follow, and they may be needed in order for the CLI to properly function. [Clone your new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) locally, and once inside the repository folder, run the following commands in your terminal to update your repository with the tags: + +```shell +# If you give another name to your gitops-template repository, update it also +git remote add upstream git@github.com:kubefirst/gitops-template.git +git fetch upstream +git push --tags +``` + +Now you can use the `--gitops-template-url` flag pointing to your new repository when creating a new Kubernetes cluster. + +When the kubefirst CLI checks out the `gitops-template-url` flag for the repository URL, it will default to checking out the git tag that matches the CLI's version. For example a v2.0.0 CLI would check out the `gitops-template-url` at the tag `v2.0.0`. This is not always the desired effect, as you may be forking in order to introduce some new changes to the `gitops-template` repository structure. In order to checkout the `main` branch of your forked `gitops-template` repository instead of the version tag, you need to also include the `--gitops-template-branch main` flag with your `create` command. diff --git a/versioned_docs/version-2.2/common/install-clouds.mdx b/versioned_docs/version-2.2/common/install-clouds.mdx new file mode 100644 index 00000000..3ecc9d56 --- /dev/null +++ b/versioned_docs/version-2.2/common/install-clouds.mdx @@ -0,0 +1,106 @@ +There are a few ways to install kubefirst, whether you have a cluster already or don't. + + + +# Install Kubefirst + +## Step 1: Install kubefirst console + + + +# Helm + +This will install our platform installer tools to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# Helm (ARM / M1 Mac / M2 Mac) + +This will install our platform installer UI to your existing cluster so you can +create your new management cluster in your favorite cloud provider using your +favorite git provider. + +This example shows a couple additional helm values settings that enable mongo to +run on the ARM architecture. + +``` +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --namespace kubefirst --create-namespace \ +--set=mongodb.image.repository=arm64v8/mongo \ +--set=mongodb.image.tag=latest \ +--set=mongodb.persistence.mountPath=/data/db \ +--set=mongodb.extraEnvVarsSecret=kubefirst-initial-secrets \ +kubefirst/kubefirst + +kubectl port-forward svc/kubefirst-console 8080:8080 +``` + +Then connect to the provisioning tool at [http://localhost:8080](http://localhost:8080) + +# No kubernetes yet? + +**No cluster? No problem!** Let us create your bootstrap cluster for you as well. We'll install our provisioning tool into it to create your permanent infrastructure. + +``` +brew install kubefirst/tools/kubefirst + +kubefirst launch up +``` + +Then connect to the provisioning tool at +[https://console.kubefirst.dev](https://console.kubefirst.dev ) + +:::note + +The kubefirst.dev domain is only available after `kubefirst launch up` and resolves to the host machine. + +::: + +# CLI GitHub + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxx + +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --domain-name your-company.io \ + --cluster-name kubefirst-mgmt \ + --github-org your-github-organization-name +``` + +# CLI GitLab + +```shell +export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxx + +kubefirst aws create \ + --alerts-email yourdistro@your-company.io \ + --git-provider gitlab \ + --gitlab-group your-gitlab-group \ + --domain-name your-domain.io \ + --cluster-name kubefirst +``` + + + +## Step 2: Install your kubefirst management cluster + +:::note: if you installed via CLI GitHub/GitLab you can skip this step +::: + +Provide details about your preferred git provider, cloud provider, access, and cluster details and let kubefirst do the rest. + +![kubefirst user interface showing cloud and git options](../img/console/installer.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/metaphor.mdx b/versioned_docs/version-2.2/common/metaphor.mdx new file mode 100644 index 00000000..c0e554d6 --- /dev/null +++ b/versioned_docs/version-2.2/common/metaphor.mdx @@ -0,0 +1,147 @@ + +# Metaphor + +The [metaphor](https://github.com/kubefirst/metaphor-template) repository is an example application with source code, builds, and GitOps delivery used to showcase various features, integrations, and best practices of the kubefirst platform. It's useful to keep on your new platform as a place to test CI changes or anything you need to verify on the platform. The metaphor app has CI/CD that delivers each application to a development, staging, and production namespace in your Kubernetes cluster. The metaphor service applications' secrets in HashiCorp Vault are bound to the metaphor application through the use of the external secrets operator, a handy Kubernetes utility to keep Kubernetes secrets in sync with the Vault, the source of truth. It demonstrates how DNS entries are automatically created in AWS Route 53 using external DNS, and has auto-renewing, short-lived certificates generated by cert-manager and the Let's Encrypt cluster-issuer. + +## Best Practices + +The `metaphor` applications provide a demonstration space for application best practices in a tangible way that's easy to apply to other projects. When engineers discover good patterns to use in other projects, they can add that new idea in the most straightforward way possible to the Metaphor applications as well. By doing so our engineering team can fully engage with the best application approaches. + +## CI/CD + +The `metaphor` applications come with complete CI/CD processes including automated builds, container Helm chart creation, container and Helm chart publishing, linting, tests, GitOps deployments to `development`, `staging`, and `production` namespaces, release management, version management, and hotfixes. It serves as an excellent proving ground for changes to the CI/CD layer. + +When a new version of our CI is needed, it's best to adopt that new version of the CI in a `metaphor` application first. Run through the adjustments to your automation and test it through all of your environments and Kubernetes clusters without impacting the applications that your engineers and users depend on. + +## Kubernetes Representations + +The `metaphor` applications are multi-instance load balanced applications. It's deployed to the `development`, `staging`, and `production` namespaces in your `kubefirst` cluster. + +![Metaphor Diagram](../img/metaphor/metaphor-diagram-light.png#light-mode)![Metaphor Diagram](../img/metaphor/metaphor-diagram-dark.png#dark-mode) + +The Kubernetes manifests produced by the `metaphor` applications CI include a working example of a Kubernetes deployment with downstream ReplicaSet and pods, a service account with a security context used, a service to make the application available to the cluster, and an Ingress to make the service available outside the cluster. + +## Ingress Integrations + +The Ingress manifest demonstrates integration with our automated approach to DNS management, load balancer management, and TLS/SSL certificate creation and renewal. + +``` yaml +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + annotations: + kubernetes.io/ingress.class: nginx + # Change the next line to "letsencrypt-staging" while testing adjustments, change to "letsencrypt-prod" after confirming LE certificate was issued + cert-manager.io/cluster-issuer: "letsencrypt-prod" + name: metaphor + labels: + run: metaphor +spec: + rules: + - host: metaphor-development.your-company.io + http: + paths: + - backend: + serviceName: metaphor + servicePort: 3000 + path: / + tls: + - secretName: metaphor-tls + hosts: + - metaphor-development.your-company.io +``` + +## Some Cool Automated Things to Note + +For an AWS Cloud selection(`kubefirst create --cloud aws`): + +- the value specified in `spec.rules.host` will automatically create a route53 CNAME that is bound to the Ingress elastic load balancer. +- The `cert-manager.io/cluster-issuer` annotation will prompt `cert-manager` to automatically create a certificate for your application and will store that cert in the `secretName` specified. +- Nginx will automatically route traffic to the `metaphor` applications service based on the path-based/host-based routing specified in `spec.rules`. + +For a local selection(`kubefirst local`): + +- A local DNS route will be produced with SSL certificates generated for you +- This certificates can be added to your machine truststore to allow a more smooth experience + +## Environment Configurations and Secrets + +The `metaphor` applications also include a working example of how to leverage a multi-environment secrets management paradigm powered by **Vault** and `external-secrets`. + +There is also a ConfigMap implementation to demonstrate how to leverage non-sensitive configuration values. + +## Datadog Integrations + +The `metaphor` applications are set up to provide cloud and container observability and monitoring best practices with **Datadog**. It demonstrates using **Datadog** for `metaphor` application logs, container statistics, application metrics, application performance monitoring, dashboard, and alerting. + +## Secrets Management + +The `metaphor` applications leverages HashiCorp **Vault** for secrets management. **Vault** runs in the `mgmt` cluster and metaphor runs in `preprod` and `production`, so it serves as an example for secrets management. To read more see our [Vault documentation](./vault.mdx). + +## How its CI/CD is defined + +These are the key files/folders to be replicated in case, you want to use `metaphor` to your application: + +```shell +.argo +.github +chart/Metaphor +build +.gitlab-ci.yaml +``` + +- **Concept 1:** If you are using GitHub (local or cloud), it will be trigger based at `.github/workflows/`; Or if you are using GitLab, installation, it will be trigger based at `.gitlab-ci.yaml`. The idea is that these are used for simply triggering an **Argo Workflows**. +- **Concept 2:** By using **Argo Workflows** to drive your CI jobs you can re-use some of the **CWFT** we provide and also create your own **CWFTs** to help build your toolset, the idea here is to have more generic automations that are not bound to a given git provider tool. +- **Concept 3:** Use our **CWFTs** as the basis to build your library of automations by adding new ones that fit your application needs. +- **Concept 4:** Application is build from a Dockerfile that is defined on the `build` folder. + +## Metaphor and Helm + +We provide a sample application that is packed with Helm, you don't need to use Helm. if you want to use it, we show how to handle charts update flow based on Helm charts and GitOps. + +The files you be interested are: + +```shell +chart/Metaphor +``` + +There is a CWFT meant to bump a chart version and update chart museum. This automation is to guide how to leverage the tooling already embedded on kubefirst to serve applications internally. + +## Wrapping up + +Here is described how metaphor gives you a demo of most of the tooling added to your cluster once the installation is finished. It is added in a way that self-unfold once the cluster is ready. + +Want to learn more, check: + +- [GitOps](./gitops.mdx) +- [Vault](./vault.mdx) + +## Tips + +### Metaphor and Local - Special Attention + +If you want to use it as base of your application, and bring a new application to a local installation. Be aware, as we use user accounts for local, you need to add a GitHub runner deployment for that new application repository. + +Reference: [runnerdeployment.yaml](https://github.com/kubefirst/gitops-template/blob/main/k3d-github/cluster-types/mgmt/components/github-runner/runnerdeployment.yaml) + +At your `gitops` repository go to `components/github-runner/runnerdeployment.yaml` and clone this file, then update the property `spec.template.spec.repository` to point to `your-user/your-repo`. This will deploy a new set of runners to observe that repository for you, allowing CI triggers to be executed. + +```yaml +... +spec: + replicas: 1 + template: + spec: + repository: / +... +``` + +### Can I add gates to prevent metaphor to move between development to production? + +Yes, the idea of our current approach of self-unfold to all environments it is to allow you to test the tires of your cluster with minimal need of clicks on the UI, but yes you can create and add a logic on the deployment artifacts to hold until a giving situation is satisfied. + +You want to be aware of this artifacts at your `gitops` repository, where the `metaphor` and your applications probably will be added to be deployed on this giving environments. + +- components/development +- components/staging +- components/production diff --git a/versioned_docs/version-2.2/common/partials/common/_terminal-output.mdx b/versioned_docs/version-2.2/common/partials/common/_terminal-output.mdx new file mode 100644 index 00000000..5879c03c --- /dev/null +++ b/versioned_docs/version-2.2/common/partials/common/_terminal-output.mdx @@ -0,0 +1,3 @@ +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/aws/github/handoff-screen.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/partials/github/_prerequisites.mdx b/versioned_docs/version-2.2/common/partials/github/_prerequisites.mdx new file mode 100644 index 00000000..748f4a36 --- /dev/null +++ b/versioned_docs/version-2.2/common/partials/github/_prerequisites.mdx @@ -0,0 +1,5 @@ +### GitHub Prerequisites + +- A GitHub [organisation](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). +- A new GitHub [account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) for your `kbot` automation user. +- A GitHub [personal access token](../../../common/git-auth.mdx) for your `kbot` account. diff --git a/versioned_docs/version-2.2/common/partials/github/_tokens.mdx b/versioned_docs/version-2.2/common/partials/github/_tokens.mdx new file mode 100644 index 00000000..44b89e73 --- /dev/null +++ b/versioned_docs/version-2.2/common/partials/github/_tokens.mdx @@ -0,0 +1,14 @@ +kubefirst uses a GitHub token to authenticate with the GitHub API. Tokens can be used to perform various actions on a user's behalf, such as creating, and deleting repository files. kubefirst uses a limited number of scopes (what is allowed with the issued token) to provision the kubefirst platform such as creating GitHub repositories and updating GitHub repository webhook URL. + +kubefirst issue GitHub Tokens at the beginning of the installation using [GitHub device login flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow). + +## GitHub Token Scopes + +kubefirst uses the following scopes to provision the kubefirst platform: +![GitHub Token Scopes](../../../img/common/github/scopes.png) + +## How to create a GitHub Token + +There are different ways to create a GitHub token. The easiest way is to start the kubefirst installer, and follow the screen instructions. It will guide you to issue a token with the list of scope described above. + +There are other ways to create a GitHub token. You can login into your GitHub account and issue a Personal Access token following the list of scopes above. With the manually generated token, you can provide it via environment variable: `export GITHUB_TOKEN`. \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/partials/gitlab/_prerequisites.mdx b/versioned_docs/version-2.2/common/partials/gitlab/_prerequisites.mdx new file mode 100644 index 00000000..90089e0d --- /dev/null +++ b/versioned_docs/version-2.2/common/partials/gitlab/_prerequisites.mdx @@ -0,0 +1,8 @@ +### GitLab + +- Create or use an existing [GitLab account](https://gitlab.com). +- Create a [GitLab group](https://docs.gitlab.com/ee/user/group/) developer permissions. +- A GitLab [personal access token](../../../common/git-auth.mdx) for your `kbot` account. + +:::note GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization. +::: \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/partials/gitlab/_tokens.mdx b/versioned_docs/version-2.2/common/partials/gitlab/_tokens.mdx new file mode 100644 index 00000000..d76d99a0 --- /dev/null +++ b/versioned_docs/version-2.2/common/partials/gitlab/_tokens.mdx @@ -0,0 +1,15 @@ +kubefirst uses a GitLab token to authenticate with the GitLab API. Tokens can be used to perform various actions on a user's behalf, such as creating, and deleting repository files. kubefirst uses a limited number of scopes (what is allowed with the issued token) to provision the kubefirst platform such as creating GitLab repositories and updating GitLab repository webhook URL. + +kubefirst issue GitLab Tokens at the beginning of the installation using [GitLab device login flow](https://docs.gitlab.com/ce/api/oauth2.html). + +## GitLab Token Scopes + +kubefirst uses the following scopes to provision the kubefirst platform: + +![GitLab Token Scopes](../../../img/common/gitlab/scopes.png) + +## How to create a GitLab Token + +There are different ways to create a GitLab token. The easiest way is to start the kubefirst installer, and follow the screen instructions. It will guide you to issue a token with the list of scope described above. + +There are other ways to create a GitLab token. You can login into your GitLab account and issue a Personal Access Token following the list of scopes above. With the manually generated token, you can provide it via environment variable: `export GITLAB_TOKEN`. \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/platform.mdx b/versioned_docs/version-2.2/common/platform.mdx new file mode 100644 index 00000000..0dac47f9 --- /dev/null +++ b/versioned_docs/version-2.2/common/platform.mdx @@ -0,0 +1,158 @@ +# kubefirst Platforms + +## What is kubefirst? + +kubefirst is a fully automated and operational open source platform that includes some of the most popular open source tools available in the Kubernetes space, all working together from a single command. + +We support local, AWS, and Civo clouds. By running our CLI commands against your empty environment, you'll get a GitOps cloud management and application delivery ecosystem complete with automated Terraform workflows, Vault secrets management, GitLab or GitHub integrations with Argo, and demo applications that demonstrate how it all pieces together. + +![kubefirst Architecture](../img/common/kubefirst/architecture-light.png#light-mode)![kubefirst Architecture](../img/common/kubefirst/architecture-dark.png#dark-mode) + +--- + +## Choose your platform type + +Choose one of the available options below + +
+
+
+
+ Local k3d with GitHub +
+
+

kubefirst Local (k3d with GitHub)

+

+ The fastest way to explore the kubefirst platform! +

+

+ With kubefirst k3d, you can explore some of the best parts of the kubefirst platform running for free on a local k3d cluster in less than 5 minutes - without any cloud costs or domain prerequisites. +

+
+
+
+ +
+
+
+
+
+
+
+ Local k3d with GitLab +
+
+

🆕 kubefirst Local (k3d with GitLab)

+

+ The fastest way to explore the kubefirst platform! +

+

+ With kubefirst k3d, you can explore some of the best parts of the kubefirst platform running for free on a local k3d cluster in less than 5 minutes - without any cloud costs or domain prerequisites. +

+
+
+
+ +
+
+
+
+
+
+
+
+
+ Civo Cloud with GitHub +
+
+

🆕 kubefirst on Civo Cloud (GitHub)

+

+ The perfect cloud environment when Kubernetes will be the center of attention. +

+

A simple cloud footprint with a powerful open source cloud native tool set for identity and infrastructure management, application delivery, and secrets management. Cloud native infrastructure with incredibly fast provisioning times. +

+
+
+
+ +
+
+
+
+
+
+
+ Civo Cloud with GitLab +
+
+

🆕 kubefirst on Civo Cloud (GitLab)

+

+ The perfect cloud environment when Kubernetes will be the center of attention. +

+

A simple cloud footprint with a powerful open source cloud native tool set for identity and infrastructure management, application delivery, and secrets management. Cloud native infrastructure with incredibly fast provisioning times. +

+
+
+
+ +
+
+
+
+
+
+
+
+
+ AWS Cloud with GitHub +
+
+

kubefirst on AWS (GitHub)

+

+ Our AWS cloud platform can accommodate all the needs of your enterprise and supports the GitHub git provider. All you need is a domain in addition to a hosted zone, and within 35 minutes of running a single command, you'll have a secure EKS infrastructure management and application delivery platform. +

+
+
+
+ +
+
+
+
+
+
+
+ AWS Cloud with GitLab +
+
+

kubefirst on AWS (GitLab)

+

+ Our AWS cloud platform can accommodate all the needs of your enterprise and supports the GitLab git provider. All you need is a domain in addition to a hosted zone, and within 35 minutes of running a single command, you'll have a secure EKS infrastructure management and application delivery platform. +

+
+
+
+ +
+
+
+
+
diff --git a/versioned_docs/version-2.2/common/prerequisites/Prerequisites.jsx b/versioned_docs/version-2.2/common/prerequisites/Prerequisites.jsx new file mode 100644 index 00000000..2a663c82 --- /dev/null +++ b/versioned_docs/version-2.2/common/prerequisites/Prerequisites.jsx @@ -0,0 +1,9 @@ +const Prerequisites = () => { + return ( +
+ +
+ ) +} + +export default Prerequisite; \ No newline at end of file diff --git a/versioned_docs/version-2.2/common/telemetry.mdx b/versioned_docs/version-2.2/common/telemetry.mdx new file mode 100644 index 00000000..2936fba2 --- /dev/null +++ b/versioned_docs/version-2.2/common/telemetry.mdx @@ -0,0 +1,17 @@ +# kubefirst Telemetry + +kubefirst collects data in order to optimize future releases. By collecting metrics on what type of clusters are being deployed and how they are being used, kubefirst prioritizes the features that are being used across the majority of the user base. While we rely on this data to make improvements to the platform, you are always allowed to opt out for any reason. + +## What Metrics are collected? + +- `cli_version`: The version of CLI being used (e.g. `2.0.0`) +- `cloud_provider` The cloud environment (`k3d`|`aws`|`civo`) +- `cluster_id`: The ID of the cluster being created (e.g. `123ABC`) +- `cluster_type`: The type of cluster being created (`mgmt`) +- `domain`: The domain of the cluster being created (e.g. `kubefirst.io`) +- `git_provider`: Type of git provider leveraged (`github`|`gitlab`) +- `kubefirst_team`: For internal use only +- `kubefirst_team_info`: For internal use only +- `machine_id`: An anonymized ID representing a distinct client host (e.g. `123456-123abc-abc123123abc-123123`) + +When installing your kubefirst cluster through the CLI, append the `--use-telemetry=false` flag to opt out of this process. diff --git a/versioned_docs/version-2.2/common/terraform.mdx b/versioned_docs/version-2.2/common/terraform.mdx new file mode 100644 index 00000000..b1f9648b --- /dev/null +++ b/versioned_docs/version-2.2/common/terraform.mdx @@ -0,0 +1,50 @@ +Terraform is our infrastructure as code layer and we manage our Terraform workflows with `atlantis` automation. + +## Making Changes In Terraform + +### Automatic Plans With Atlantis + +Any change request that includes a .tf file will prompt `atlantis` to wake up and run your Terraform plan. Atlantis will post the plan's result to your change request as a comment within a minute or so. + +Review and approve the change request. + +You can always run a new Terraform plan by commenting directly in your pull request with the words `atlantis plan`. + +### Apply and Merge + +Add the comment `atlantis apply` in the approved change request. This will prompt Atlantis to wake up and run your `terraform apply`. + +The apply results will be added to your change request comments by Atlantis. + +If the apply is successful, your code will automatically be merged with main, your change request will be closed, and the state lock will be removed in Atlantis. + +## Managing Terraform State + +The following table shows how state is stored based on your installation selection: + +| State Backed | AWS | Local | Civo | +|-------------------|-----|-------|------| +| AWS S3 Bucket | X | | | +| Civo object store | | | X | +| MinIO (locally) | | X | | + +## Tips + +### What is the general flow of changes using Atlantis for IaC? + +- **Create a Commit and Change Request:** The change described by Terraform instructions will be created in a PR at a folder which [Atlantis is listening for it](https://github.com/kubefirst/gitops-template/blob/main/aws-github/atlantis.yaml). Once the Change Request is created on GitHub/GitLab, Atlantis will plan it and show possible impacts of it. +- **Approve the change:** Once you are ready, someone with access will provide `atlantis apply` on the change request, triggering the process of executing the `plan` created. +- **Change is applied by Atlantis**: Atlantis will execute the Terraform plan, and Terraform will update shared statestore with new current state changes, change request will be merged to main, reflecting the new desired state. + +:::note The term "Change Request" is a "Pull Request" on GitHub and "Merge Request" on GitLab. + +### What can I use Atlantis & Terraform for? + +For example, you can use your `gitops` repository to help track the creation of repositories: + +- [AWS + GitHub repository template](https://github.com/kubefirst/gitops-template/blob/main/aws-github/terraform/github/repos.tf) +- [local + GitHub repository template](https://github.com/kubefirst/gitops-template/blob/main/k3d-github/terraform/github/repos.tf) + +With Terraform using the S3 based state store, you can add any Terraform file to the `gitops` repository on which [Atlantis is listening for](https://github.com/kubefirst/gitops-template/blob/main/aws-github/atlantis.yaml) and Atlantis will try to plan and when approved to apply such plan for you. + +Beyond repositories and users, Atlantis allow you to have your IaC demands to be tracked by your main branch registry. Easing up the usage of Terraform based workflows to update the infrastructure you are operating. diff --git a/versioned_docs/version-2.2/common/vault.mdx b/versioned_docs/version-2.2/common/vault.mdx new file mode 100644 index 00000000..cce5bffe --- /dev/null +++ b/versioned_docs/version-2.2/common/vault.mdx @@ -0,0 +1,205 @@ + +[Vault](https://www.vaultproject.io) is an open source secrets manager and identity provider created by HashiCorp. + +### Token authentication + +![Vault section of the handoff screen](../img/vault/handoff-screen.png) + +Your first login to Vault will be with the root token which has full administrative permissions. As mentioned in the handoff screen (the purple screen at the end of the installation), it is sorted in a secret named `vault-unseal-secret`, which is in the `vault` namespace of your newly deployed cluster. To read the value, use [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) (which is already in the `~/.k1/` tools folder), and run the following command: + +```shell +~/.k1/tools/kubectl -n vault get secrets/vault-unseal-secret --template='{{index .data "root-token"}}' | base64 -d +``` + +It will output the root token. Copy it, then open your browser, and navigate to your Vault instance. Select `Token` and paste the value into the password field. + +![HashiCorp Vault Token Login](../img/kubefirst/vault/token-login.png) + +While logged in with the root token, navigate to the secret at `Users -> kbot`. This secret is the username, and OIDC password for the kubefirst bot user named `kbot`. Copy the value, log out of Vault and use it to authenticate with this user in the next section. + +### Username authentication (human users) + +When logging in with users instead of tokens, select method `Username` as the login method on the login screen. Enter `kbot` as the username, and paste the password you collected in the Password field and log in. + +![HashiCorp Vault Sign in Page](../img/kubefirst/vault/vault-userpass.png) + +This is the login experience that your team will use when authenticating with Vault. Initially, there will only be a singular `kbot` user created that represents the kubefirst bot account. You can pull request additional admins and developers from your team onto the platform, and they will all log in using the Username method. + +Once a user is logged into Vault with Username auth, they will be automatically provided single sign-on (SSO) access to Argo Workflows, Argo CD, and the [kubefirst Console application](https://github.com/kubefirst/console/). + +### Kubernetes authentication + +The `external-secrets-operator` application will be preconfigured with a service account that can pull secrets from your cluster's Vault instance. This is accomplished by leveraging the `kubernetes/kubefirst/` auth backend. By default, external-secrets will be able to pull your cluster secrets, and make them available as native Kubernetes secrets for your applications to leverage. + +### Additional auth methods + +There are other authentication schemes available to you as well: [https://www.vaultproject.io/docs/auth](https://www.vaultproject.io/docs/auth) + +## Secrets Setup for Applications + +### Storing secrets in Vault + +While logged into Vault, navigate to secrets path `secret/development/metaphor`. + +![HashiCorp Vault Secrets Examples](../img/kubefirst/vault/vault-secret-example.png) + +Here you can see we have two secrets stored at named `SECRET_ONE` and `SECRET_TWO` with two "secret values". These two values are obviously not actually sensitive and are for demonstration purposes only. Let's explore how secrets work. + +### Creating Kubernetes Secrets From Vault Secrets + +If you look in your new metaphor repository in GitLab or GitHub, you'll find a Helm template file at path `metaphor/charts/metaphor/templates/external-secrets.yaml` + +```yaml +apiVersion: "external-secrets.io/v1alpha1" +kind: ExternalSecret +metadata: + name: {{ template "metaphor.fullname" . }} + labels: + chart: "{{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}" +spec: + target: + name: {{ template "metaphor.fullname" . }} + secretStoreRef: + kind: ClusterSecretStore + name: vault-kv-secret + refreshInterval: "10s" + data: + - remoteRef: + key: {{ .Values.vaultSecretPath }} + property: SECRET_ONE + secretKey: SECRET_ONE + - remoteRef: + key: {{ .Values.vaultSecretPath }} + property: SECRET_TWO + secretKey: SECRET_TWO +``` + +This is going to be a very common file type for you on the kubefirst platform. This Kubernetes resource deploys with metaphor, connecting to the `vault-kv-secret` cluster secret store, and pulls secrets from the path specified in the values.yaml property `vaultSecretPath`. You can either pull all secrets from Vault into the Kubernetes secret, or as this secret demonstrates, you can also specify exactly which specific key/value pairs to pull when creating the secret. + +The result will be a native Kubernetes secret, which can be used by your application. Since the path is driven by Helm `values.yaml` values, the source for these secrets can be different in your different environments. For example, when you go to your `gitops` repository and look at `gitops/components/staging/metaphor/values.yaml` you'll see on the last line that we're pulling the staging secrets from the staging path in Vault. + +```yaml +metaphor: + ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + cert-manager.io/cluster-issuer: "letsencrypt-prod" + hosts: + - host: metaphor-staging.feedkray.com + paths: + - / + tls: + - secretName: metaphor-tls + hosts: + - metaphor-staging.feedkray.com + vaultMountPoint: kubefirst + vaultSecretPath: staging/metaphor +``` + +### Confirming Your Kubernetes Secrets + +Applying the above ExternalSecret resource to your Kubernetes namespace is enough to produce a Kubernetes secret which will stay in sync with Vault's values. Let's confirm: + +#### 1. Get all secrets in the staging namespace + +```shell +kubectl -n staging get secrets + +NAME TYPE DATA AGE +default-token-z7crd kubernetes.io/service-account-token 3 13h +metaphor-frontend-sa-token-668gq kubernetes.io/service-account-token 3 12h +metaphor-frontend-tls kubernetes.io/tls 2 12h +metaphor-go-sa-token-bx2gk kubernetes.io/service-account-token 3 12h +metaphor-go-staging Opaque 2 12h +metaphor-go-tls kubernetes.io/tls 2 12h +metaphor-sa-token-v964z kubernetes.io/service-account-token 3 12h +metaphor-staging Opaque 2 12h +metaphor-tls kubernetes.io/tls 2 12h +``` + +#### 2. Get the YAML of the one named `metaphor-staging` + +```shell +kubectl -n staging get secret metaphor-staging -oyaml + +apiVersion: v1 +data: + SECRET_ONE: c3RhZ2luZyBzZWNyZXQgMQ== + SECRET_TWO: c3RhZ2luZyBzZWNyZXQgMg== +immutable: false +kind: Secret +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"external-secrets.io/v1alpha1","kind":"ExternalSecret","metadata":{"annotations":{},"labels":{"argocd.argoproj.io/instance":"metaphor-staging","chart":"metaphor-0.1.0-rc.e54452a0"},"name":"metaphor-staging","namespace":"staging"},"spec":{"data":[{"remoteRef":{"key":"staging/metaphor","property":"SECRET_ONE"},"secretKey":"SECRET_ONE"},{"remoteRef":{"key":"staging/metaphor","property":"SECRET_TWO"},"secretKey":"SECRET_TWO"}],"refreshInterval":"10s","secretStoreRef":{"kind":"ClusterSecretStore","name":"vault-kv-secret"},"target":{"name":"metaphor-staging"}}} + reconcile.external-secrets.io/data-hash: fdc2f634a31c8e93dd8d47e940aa7939 + creationTimestamp: "2022-10-18T04:21:57Z" + labels: + argocd.argoproj.io/instance: metaphor-staging + chart: metaphor-0.1.0-rc.e54452a0 + name: metaphor-staging + namespace: staging + ownerReferences: + - apiVersion: external-secrets.io/v1beta1 + blockOwnerDeletion: true + controller: true + kind: ExternalSecret + name: metaphor-staging + uid: 890fe79f-f48a-4dac-85c6-ac790ffc4147 + resourceVersion: "21526" + uid: 1c2c9cd8-6aed-4e65-8e5c-57d3fd578b4d +type: Opaque +``` + +#### 3. Confirm that it's your value from Vault + +```shell +echo "c3RhZ2luZyBzZWNyZXQgMQ==" | base64 -d + +staging secret 1% +``` + +### Using Those Secrets in Your App + +Now that you have native Kubernetes secrets available, you can use them however you choose. Our metaphor example uses them as environment variables as shown here: + +![Metaphor Secrets on GitLab](../img/kubefirst/vault/metaphor-secret-use-in-deployment.png) + +> Note: There are a ton of other ways secrets can be leveraged in your app, like +[using secrets as files on pods](https://kubernetes.io/docs/concepts/configuration/secret/), or [storing your Docker Hub login](https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets). + +## Tips + +### How can I change my users password? + +Simple, if you are the owner of the user. + +- Log with the user on Vault: `https://vault.$yourdomain.com/ui/vault/auth?with=userpass` +- Go to `Access` tab +- Select `Auth Methods` (left side) +- Select `userpass` (right side) +- Select your-user (right side) +- Click Edit user (right side) +- Fill new password (right side) +- Click `Save` (right side) + +![HashiCorp Vault Sign in](../img/kubefirst/vault/kubefirst-1-11-vault-update-password.gif) + +### Who can change users password? + +- Yourself logged with your user/password +- Someone with the Vault root token + +Vault Policies references: + +- [AWS with GitHub](https://github.com/kubefirst/gitops-template/blob/main/aws-github/terraform/vault/policies.tf) +- [AWS with GitLab](https://github.com/kubefirst/gitops-template/blob/main/aws-gitlab/terraform/vault/policies.tf) +- [Civo with GitHub](https://github.com/kubefirst/gitops-template/blob/main/civo-github/terraform/vault/policies.tf) +- [Civo with GitLab](https://github.com/kubefirst/gitops-template/blob/main/civo-gitlab/terraform/vault/policies.tf) +- [local with GitHub](https://github.com/kubefirst/gitops-template/blob/main/k3d-github/terraform/vault/policies.tf) +- [local with GitLab](https://github.com/kubefirst/gitops-template/blob/main/k3d-gitlab/terraform/vault/policies.tf) + +### Can someone with the root token update my password? + +yes, just follow the steps at **"How can I change my users password?"** select a user, and edit the user. The root token gives full access to update Vault secrets. diff --git a/versioned_docs/version-2.2/community/index.md b/versioned_docs/version-2.2/community/index.md new file mode 100644 index 00000000..df166b04 --- /dev/null +++ b/versioned_docs/version-2.2/community/index.md @@ -0,0 +1,17 @@ +# Community + +## Slack + +Join the `kubefirst` slack workspace by following [this link](https://join.slack.com/t/kubefirst/shared_invite/zt-r0r9cfts-OVnH0ooELDLm9n9p2aU7fw). Ask questions in the `#helping-hands` channel. + +## Issues + +Open an issue or request [here](https://github.com/kubefirst/kubefirst/issues) + +## Zoom + +We're happy to engage with you to talk through your use cases and any points of clarification needed. [Book a meeting](https://calendly.com/kubefirst/intro) with us so we can help you on your way. + +## Email + +To request more information or schedule a demo email diff --git a/versioned_docs/version-2.2/constants.js b/versioned_docs/version-2.2/constants.js new file mode 100644 index 00000000..acd6e327 --- /dev/null +++ b/versioned_docs/version-2.2/constants.js @@ -0,0 +1,5 @@ +export const AWS_LOGO_URL = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/93/Amazon_Web_Services_Logo.svg/512px-Amazon_Web_Services_Logo.svg.png?20170912170050"; +export const CIVO_LOGO_URL = "https://www.civo.com/assets/public/brand-assets/civo-logo-colour-60cc1622dedf346f7afde1fff760523f731b0aac106a5465af98ff4073114b74.svg"; +export const K3D_LOGO_URL = "https://k3d.io/v5.5.1/static/img/k3d_logo_black_blue.svg"; +export const GITHUB_LOGO_URL = "https://assets.kubefirst.com/console/github.svg"; +export const GITLAB_LOGO_URL = "https://assets.kubefirst.com/console/gitlab.svg"; \ No newline at end of file diff --git a/versioned_docs/version-2.2/img/aws/github/handoff-screen.png b/versioned_docs/version-2.2/img/aws/github/handoff-screen.png new file mode 100644 index 00000000..baf1e1e9 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/github/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/aws/github/installation-diagram-dark.png b/versioned_docs/version-2.2/img/aws/github/installation-diagram-dark.png new file mode 100644 index 00000000..5199be31 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/github/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/aws/github/installation-diagram-light.png b/versioned_docs/version-2.2/img/aws/github/installation-diagram-light.png new file mode 100644 index 00000000..2d114bc3 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/github/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/aws/gitlab/handoff-screen.png b/versioned_docs/version-2.2/img/aws/gitlab/handoff-screen.png new file mode 100644 index 00000000..4a1538f4 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/gitlab/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-dark.png b/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-dark.png new file mode 100644 index 00000000..1f801ae2 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-light.png b/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-light.png new file mode 100644 index 00000000..2e8e4926 Binary files /dev/null and b/versioned_docs/version-2.2/img/aws/gitlab/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/civo/deceptive-warning.png b/versioned_docs/version-2.2/img/civo/deceptive-warning.png new file mode 100644 index 00000000..dc74fbb4 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/deceptive-warning.png differ diff --git a/versioned_docs/version-2.2/img/civo/github/handoff-screen.png b/versioned_docs/version-2.2/img/civo/github/handoff-screen.png new file mode 100644 index 00000000..f9af36f0 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/github/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/civo/github/installation-diagram-dark.png b/versioned_docs/version-2.2/img/civo/github/installation-diagram-dark.png new file mode 100644 index 00000000..44a41f7b Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/github/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/civo/github/installation-diagram-light.png b/versioned_docs/version-2.2/img/civo/github/installation-diagram-light.png new file mode 100644 index 00000000..c3fb6836 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/github/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/civo/gitlab/handoff-screen.png b/versioned_docs/version-2.2/img/civo/gitlab/handoff-screen.png new file mode 100644 index 00000000..72a56939 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/gitlab/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-dark.png b/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-dark.png new file mode 100644 index 00000000..2ebe3e78 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-light.png b/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-light.png new file mode 100644 index 00000000..f1042322 Binary files /dev/null and b/versioned_docs/version-2.2/img/civo/gitlab/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/common/catalog/button.png b/versioned_docs/version-2.2/img/common/catalog/button.png new file mode 100644 index 00000000..138b8c64 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/catalog/button.png differ diff --git a/versioned_docs/version-2.2/img/common/catalog/page.png b/versioned_docs/version-2.2/img/common/catalog/page.png new file mode 100644 index 00000000..331c4060 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/catalog/page.png differ diff --git a/versioned_docs/version-2.2/img/common/catalog/services.png b/versioned_docs/version-2.2/img/common/catalog/services.png new file mode 100644 index 00000000..e1c4a1c1 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/catalog/services.png differ diff --git a/versioned_docs/version-2.2/img/common/github/atlantis-comments.png b/versioned_docs/version-2.2/img/common/github/atlantis-comments.png new file mode 100644 index 00000000..86c21359 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/github/atlantis-comments.png differ diff --git a/versioned_docs/version-2.2/img/common/github/atlantis.png b/versioned_docs/version-2.2/img/common/github/atlantis.png new file mode 100644 index 00000000..1ee8e2ee Binary files /dev/null and b/versioned_docs/version-2.2/img/common/github/atlantis.png differ diff --git a/versioned_docs/version-2.2/img/common/github/console.png b/versioned_docs/version-2.2/img/common/github/console.png new file mode 100644 index 00000000..8e4644c6 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/github/console.png differ diff --git a/versioned_docs/version-2.2/img/common/github/repositories.png b/versioned_docs/version-2.2/img/common/github/repositories.png new file mode 100644 index 00000000..0a3c81b1 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/github/repositories.png differ diff --git a/versioned_docs/version-2.2/img/common/github/scopes.png b/versioned_docs/version-2.2/img/common/github/scopes.png new file mode 100644 index 00000000..435780e9 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/github/scopes.png differ diff --git a/versioned_docs/version-2.2/img/common/gitlab/atlantis-comments.png b/versioned_docs/version-2.2/img/common/gitlab/atlantis-comments.png new file mode 100644 index 00000000..e38d1850 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/gitlab/atlantis-comments.png differ diff --git a/versioned_docs/version-2.2/img/common/gitlab/atlantis.png b/versioned_docs/version-2.2/img/common/gitlab/atlantis.png new file mode 100644 index 00000000..dafb7096 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/gitlab/atlantis.png differ diff --git a/versioned_docs/version-2.2/img/common/gitlab/console.png b/versioned_docs/version-2.2/img/common/gitlab/console.png new file mode 100644 index 00000000..401cdcc4 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/gitlab/console.png differ diff --git a/versioned_docs/version-2.2/img/common/gitlab/repositories.png b/versioned_docs/version-2.2/img/common/gitlab/repositories.png new file mode 100644 index 00000000..b86b9480 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/gitlab/repositories.png differ diff --git a/versioned_docs/version-2.2/img/common/gitlab/scopes.png b/versioned_docs/version-2.2/img/common/gitlab/scopes.png new file mode 100644 index 00000000..11dda2e4 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/gitlab/scopes.png differ diff --git a/versioned_docs/version-2.2/img/common/kubefirst/architecture-dark.png b/versioned_docs/version-2.2/img/common/kubefirst/architecture-dark.png new file mode 100644 index 00000000..34105f35 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/kubefirst/architecture-dark.png differ diff --git a/versioned_docs/version-2.2/img/common/kubefirst/architecture-light.png b/versioned_docs/version-2.2/img/common/kubefirst/architecture-light.png new file mode 100644 index 00000000..15ee53f7 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/kubefirst/architecture-light.png differ diff --git a/versioned_docs/version-2.2/img/common/kubefirst/root-credentials.png b/versioned_docs/version-2.2/img/common/kubefirst/root-credentials.png new file mode 100644 index 00000000..141d68f6 Binary files /dev/null and b/versioned_docs/version-2.2/img/common/kubefirst/root-credentials.png differ diff --git a/versioned_docs/version-2.2/img/console/installer.png b/versioned_docs/version-2.2/img/console/installer.png new file mode 100644 index 00000000..d8d2b842 Binary files /dev/null and b/versioned_docs/version-2.2/img/console/installer.png differ diff --git a/versioned_docs/version-2.2/img/gitops/gitops-diagram-dark.png b/versioned_docs/version-2.2/img/gitops/gitops-diagram-dark.png new file mode 100644 index 00000000..208284c1 Binary files /dev/null and b/versioned_docs/version-2.2/img/gitops/gitops-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/gitops/gitops-diagram-light.png b/versioned_docs/version-2.2/img/gitops/gitops-diagram-light.png new file mode 100644 index 00000000..44d8b6f7 Binary files /dev/null and b/versioned_docs/version-2.2/img/gitops/gitops-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/gitops/gitops-pipelines-dark.png b/versioned_docs/version-2.2/img/gitops/gitops-pipelines-dark.png new file mode 100644 index 00000000..388d6042 Binary files /dev/null and b/versioned_docs/version-2.2/img/gitops/gitops-pipelines-dark.png differ diff --git a/versioned_docs/version-2.2/img/gitops/gitops-pipelines-light.png b/versioned_docs/version-2.2/img/gitops/gitops-pipelines-light.png new file mode 100644 index 00000000..aedd908d Binary files /dev/null and b/versioned_docs/version-2.2/img/gitops/gitops-pipelines-light.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/argocd/app-registrations.png b/versioned_docs/version-2.2/img/kubefirst/argocd/app-registrations.png new file mode 100644 index 00000000..746a0adc Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/argocd/app-registrations.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-apps.png b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-apps.png new file mode 100644 index 00000000..9e9a0ff8 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-apps.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-source.png b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-source.png new file mode 100644 index 00000000..37a0299b Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-source.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-tf-registration.png b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-tf-registration.png new file mode 100644 index 00000000..0c03d1b7 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/argocd/argocd-tf-registration.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-github-result.png b/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-github-result.png new file mode 100644 index 00000000..11300705 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-github-result.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-result.png b/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-result.png new file mode 100644 index 00000000..318426a0 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/getting-started/cluster-create-result.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/getting-started/vault-users.png b/versioned_docs/version-2.2/img/kubefirst/getting-started/vault-users.png new file mode 100644 index 00000000..97f38e27 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/getting-started/vault-users.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-admin.png b/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-admin.png new file mode 100644 index 00000000..50cf067b Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-admin.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-export.png b/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-export.png new file mode 100644 index 00000000..4e41d9e4 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/ghost/ghost-export.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/github/github-argo-workflow.png b/versioned_docs/version-2.2/img/kubefirst/github/github-argo-workflow.png new file mode 100644 index 00000000..8031a0c1 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/github/github-argo-workflow.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/github/gitops-assets.png b/versioned_docs/version-2.2/img/kubefirst/github/gitops-assets.png new file mode 100644 index 00000000..a4f4edf3 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/github/gitops-assets.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-argo-workflow.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-argo-workflow.png new file mode 100644 index 00000000..ef0f6e7f Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-argo-workflow.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-restore-in-argocd.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-restore-in-argocd.png new file mode 100644 index 00000000..aa4e9305 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitlab-restore-in-argocd.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/gitops-assets.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitops-assets.png new file mode 100644 index 00000000..1c97bc1a Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/gitops-assets.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/kubefirst-group.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/kubefirst-group.png new file mode 100644 index 00000000..d2f79454 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/kubefirst-group.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/metaphor-in-gl.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/metaphor-in-gl.png new file mode 100644 index 00000000..fd3949a2 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/metaphor-in-gl.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitlab/restore.png b/versioned_docs/version-2.2/img/kubefirst/gitlab/restore.png new file mode 100644 index 00000000..02df47be Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitlab/restore.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitops/argocd-app-registrations.png b/versioned_docs/version-2.2/img/kubefirst/gitops/argocd-app-registrations.png new file mode 100644 index 00000000..1e844b78 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitops/argocd-app-registrations.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitops/gitlab-workflows-integration.png b/versioned_docs/version-2.2/img/kubefirst/gitops/gitlab-workflows-integration.png new file mode 100644 index 00000000..8e0954e7 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitops/gitlab-workflows-integration.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitops/gitops-gitlab.png b/versioned_docs/version-2.2/img/kubefirst/gitops/gitops-gitlab.png new file mode 100644 index 00000000..3770b798 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitops/gitops-gitlab.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/gitops/registry.png b/versioned_docs/version-2.2/img/kubefirst/gitops/registry.png new file mode 100644 index 00000000..89db440a Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/gitops/registry.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/icons/civo.png b/versioned_docs/version-2.2/img/kubefirst/icons/civo.png new file mode 100644 index 00000000..f8bb920a Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/icons/civo.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/icons/github-200x200.png b/versioned_docs/version-2.2/img/kubefirst/icons/github-200x200.png new file mode 100644 index 00000000..a2ef1c34 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/icons/github-200x200.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/icons/gitlab-200x200.png b/versioned_docs/version-2.2/img/kubefirst/icons/gitlab-200x200.png new file mode 100644 index 00000000..ca318d3c Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/icons/gitlab-200x200.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/icons/k-ray.png b/versioned_docs/version-2.2/img/kubefirst/icons/k-ray.png new file mode 100644 index 00000000..2aa51518 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/icons/k-ray.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/default-user-creation.png b/versioned_docs/version-2.2/img/kubefirst/local/default-user-creation.png new file mode 100644 index 00000000..950588b1 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/default-user-creation.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/github-argo-workflow.png b/versioned_docs/version-2.2/img/kubefirst/local/github-argo-workflow.png new file mode 100644 index 00000000..a92a2101 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/github-argo-workflow.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/gitops-registry.png b/versioned_docs/version-2.2/img/kubefirst/local/gitops-registry.png new file mode 100644 index 00000000..e0834b45 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/gitops-registry.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/metaphor-frontend-development.png b/versioned_docs/version-2.2/img/kubefirst/local/metaphor-frontend-development.png new file mode 100644 index 00000000..06dd301f Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/metaphor-frontend-development.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/metaphor-readme-update.png b/versioned_docs/version-2.2/img/kubefirst/local/metaphor-readme-update.png new file mode 100644 index 00000000..a32cc196 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/metaphor-readme-update.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/local/vault-token-login.png b/versioned_docs/version-2.2/img/kubefirst/local/vault-token-login.png new file mode 100644 index 00000000..49d17847 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/local/vault-token-login.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/metaphor/kubefirst-gitops-cicd.png b/versioned_docs/version-2.2/img/kubefirst/metaphor/kubefirst-gitops-cicd.png new file mode 100644 index 00000000..737117f3 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/metaphor/kubefirst-gitops-cicd.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/metaphor/metaphor-frontend.png b/versioned_docs/version-2.2/img/kubefirst/metaphor/metaphor-frontend.png new file mode 100644 index 00000000..7788d646 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/metaphor/metaphor-frontend.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/oss-plat-arch.png b/versioned_docs/version-2.2/img/kubefirst/oss-plat-arch.png new file mode 100644 index 00000000..eb96666c Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/oss-plat-arch.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/overview/gitops-assets-1.0.png b/versioned_docs/version-2.2/img/kubefirst/overview/gitops-assets-1.0.png new file mode 100644 index 00000000..8f78ffc4 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/overview/gitops-assets-1.0.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/overview/pro-1.0-arch.png b/versioned_docs/version-2.2/img/kubefirst/overview/pro-1.0-arch.png new file mode 100644 index 00000000..f21a5b0f Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/overview/pro-1.0-arch.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/kubefirst-1-11-vault-update-password.gif b/versioned_docs/version-2.2/img/kubefirst/vault/kubefirst-1-11-vault-update-password.gif new file mode 100644 index 00000000..047ec43f Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/kubefirst-1-11-vault-update-password.gif differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-dev.png b/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-dev.png new file mode 100644 index 00000000..b77d7763 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-dev.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-secret-use-in-deployment.png b/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-secret-use-in-deployment.png new file mode 100644 index 00000000..1487643b Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/metaphor-secret-use-in-deployment.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/token-login.png b/versioned_docs/version-2.2/img/kubefirst/vault/token-login.png new file mode 100644 index 00000000..8c37f3cf Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/token-login.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/vault-auth-method.gif b/versioned_docs/version-2.2/img/kubefirst/vault/vault-auth-method.gif new file mode 100644 index 00000000..e9b58ee0 Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/vault-auth-method.gif differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/vault-secret-example.png b/versioned_docs/version-2.2/img/kubefirst/vault/vault-secret-example.png new file mode 100644 index 00000000..0737af3a Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/vault-secret-example.png differ diff --git a/versioned_docs/version-2.2/img/kubefirst/vault/vault-userpass.png b/versioned_docs/version-2.2/img/kubefirst/vault/vault-userpass.png new file mode 100644 index 00000000..792d253c Binary files /dev/null and b/versioned_docs/version-2.2/img/kubefirst/vault/vault-userpass.png differ diff --git a/versioned_docs/version-2.2/img/local/github/handoff-screen.png b/versioned_docs/version-2.2/img/local/github/handoff-screen.png new file mode 100644 index 00000000..f58900cb Binary files /dev/null and b/versioned_docs/version-2.2/img/local/github/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/local/github/installation-diagram-dark.png b/versioned_docs/version-2.2/img/local/github/installation-diagram-dark.png new file mode 100644 index 00000000..d255cee7 Binary files /dev/null and b/versioned_docs/version-2.2/img/local/github/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/local/github/installation-diagram-light.png b/versioned_docs/version-2.2/img/local/github/installation-diagram-light.png new file mode 100644 index 00000000..f7285ec1 Binary files /dev/null and b/versioned_docs/version-2.2/img/local/github/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/local/gitlab/handoff-screen.png b/versioned_docs/version-2.2/img/local/gitlab/handoff-screen.png new file mode 100644 index 00000000..2900be18 Binary files /dev/null and b/versioned_docs/version-2.2/img/local/gitlab/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-dark.png b/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-dark.png new file mode 100644 index 00000000..6c58a9ec Binary files /dev/null and b/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-light.png b/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-light.png new file mode 100644 index 00000000..22ff577e Binary files /dev/null and b/versioned_docs/version-2.2/img/local/gitlab/installation-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-dark.png b/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-dark.png new file mode 100644 index 00000000..2ab9596d Binary files /dev/null and b/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-dark.png differ diff --git a/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-light.png b/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-light.png new file mode 100644 index 00000000..3af9274e Binary files /dev/null and b/versioned_docs/version-2.2/img/metaphor/metaphor-diagram-light.png differ diff --git a/versioned_docs/version-2.2/img/open-source/aws-account-id.png b/versioned_docs/version-2.2/img/open-source/aws-account-id.png new file mode 100644 index 00000000..544ac9a7 Binary files /dev/null and b/versioned_docs/version-2.2/img/open-source/aws-account-id.png differ diff --git a/versioned_docs/version-2.2/img/site/k-ray-light.png b/versioned_docs/version-2.2/img/site/k-ray-light.png new file mode 100644 index 00000000..3cf8d4f0 Binary files /dev/null and b/versioned_docs/version-2.2/img/site/k-ray-light.png differ diff --git a/versioned_docs/version-2.2/img/site/k-ray.png b/versioned_docs/version-2.2/img/site/k-ray.png new file mode 100644 index 00000000..d9424bb2 Binary files /dev/null and b/versioned_docs/version-2.2/img/site/k-ray.png differ diff --git a/versioned_docs/version-2.2/img/todo.jpeg b/versioned_docs/version-2.2/img/todo.jpeg new file mode 100644 index 00000000..34f4823f Binary files /dev/null and b/versioned_docs/version-2.2/img/todo.jpeg differ diff --git a/versioned_docs/version-2.2/img/vault/handoff-screen.png b/versioned_docs/version-2.2/img/vault/handoff-screen.png new file mode 100644 index 00000000..f8f5c0ef Binary files /dev/null and b/versioned_docs/version-2.2/img/vault/handoff-screen.png differ diff --git a/versioned_docs/version-2.2/index.mdx b/versioned_docs/version-2.2/index.mdx new file mode 100644 index 00000000..ef49e5bf --- /dev/null +++ b/versioned_docs/version-2.2/index.mdx @@ -0,0 +1,88 @@ +--- +slug: / +--- + +# kubefirst Platforms + +## What is kubefirst? + +kubefirst is a free, fully automated, and instantly operational open source platform that includes some of the most popular open source tools available in the Kubernetes space, all working together in a click. + +We support local, AWS, and Civo clouds, with additional clouds in beta. By running our installer in your cloud, you'll get a GitOps cloud management and application delivery ecosystem complete with automated Terraform workflows, Vault secrets management, GitLab or GitHub integrations with Argo, and a demo application that demonstrates how it all pieces together. + +![kubefirst Architecture](img/common/kubefirst/architecture-light.png#light-mode)![kubefirst Architecture](img/common/kubefirst/architecture-dark.png#dark-mode) + +--- + +# Choose your environment + +
+
+
+
+ Local k3d +
+
+

kubefirst k3d (local)

+

+ The fastest way to explore the kubefirst platform! +

+

+ With kubefirst k3d, you can explore some of the best parts of the kubefirst platform running for free on a local k3d cluster in 5 minutes - without any cloud costs or domain prerequisites. +

+
+
+
+ +
+
+
+
+
+
+
+ AWS Cloud +
+
+

AWS Cloud

+

+ Our AWS cloud platform can accommodate all the needs of your enterprise. All you need is a domain in addition to a hosted zone, and within 35 minutes of running a single command, you'll have a secure EKS infrastructure management and application delivery platform. +

+
+
+
+ +
+
+
+
+
+
+
+ Civo Cloud +
+
+

Civo Cloud

+

+ The perfect cloud environment when Kubernetes will be the center of attention. +

+

A simple cloud footprint with a powerful open source cloud native tool set for identity and infrastructure management, application delivery, and secrets management. Cloud native infrastructure with incredibly fast provisioning times. +

+
+
+
+ +
+
+
+
+
diff --git a/versioned_docs/version-2.2/k3d/credits.mdx b/versioned_docs/version-2.2/k3d/credits.mdx new file mode 100644 index 00000000..64a8c058 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/credits.mdx @@ -0,0 +1,12 @@ +--- +hide_title: true +sidebar_label: Credits +sidebar_position: 4 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: Credits for the awesome open source we use +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Credits from "@site/docs/common/credits.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/deprovision.mdx b/versioned_docs/version-2.2/k3d/deprovision.mdx new file mode 100644 index 00000000..83694cae --- /dev/null +++ b/versioned_docs/version-2.2/k3d/deprovision.mdx @@ -0,0 +1,12 @@ +--- +hide_title: true +sidebar_label: Deprovision +sidebar_position: 2 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: how to deprovision your kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Deprovision from '@site/docs/common/deprovision.mdx' + + diff --git a/versioned_docs/version-2.2/k3d/explore/argocd.mdx b/versioned_docs/version-2.2/k3d/explore/argocd.mdx new file mode 100644 index 00000000..6d707b52 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/argocd.mdx @@ -0,0 +1,8 @@ +--- +title: Argo CD +sidebar_position: 2 +--- + +import ExploreArgocd from "@site/docs/common/argocd.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/explore/gitops.mdx b/versioned_docs/version-2.2/k3d/explore/gitops.mdx new file mode 100644 index 00000000..9811501f --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/gitops.mdx @@ -0,0 +1,9 @@ +--- +title: GitOps +sidebar_position: 3 +--- + + +import ExploreGitOps from "@site/docs/common/gitops.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/explore/limitations.mdx b/versioned_docs/version-2.2/k3d/explore/limitations.mdx new file mode 100644 index 00000000..a4911ba9 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/limitations.mdx @@ -0,0 +1,28 @@ +--- +title: Limitations +sidebar_position: 1 +--- + +# Local Limitations + +## Hardware recommendation + +- OS: macOS (Intel or Apple Silicon M1/M2) or Linux AMD64 +- CPU: A Quad Core CPU or Apple Silicon with M1 or M2 chip +- RAM: 8 GB RAM +- HDD: 10 GB HD space (Docker images) + 5 GB HD space (minio-storage) + +## Docker desktop recommendation + +Allocated RAM: 5 GB +Allocated CPU: 5 Cores + +## Known issues + +- Disk: During the provisioning of the local environment, the kubefirst cli bootstrap a k3d cluster which starts downloading all docker images simultaneously. So you can experience some issues related to disk performance. +- Network bandwidth: As described above, the network bandwidth could be throttled due to downloading all docker images simultaneously. + +## Problematic use cases + +- Conventions: you are demoing the kubefirst using the kubefirst local installation at the convention. You could suffer issues with networking, mainly if the convention facility's network is poor. +- Mobile Connection: if you use the mobile connection routed to your laptop, the downloads may spend much of your data plan and suffer from the poor mobile connection. \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/explore/metaphor.mdx b/versioned_docs/version-2.2/k3d/explore/metaphor.mdx new file mode 100644 index 00000000..55866031 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/metaphor.mdx @@ -0,0 +1,8 @@ +--- +title: Metaphor +sidebar_position: 4 +--- + +import ExploreMetaphor from "@site/docs/common/metaphor.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/explore/telemetry.mdx b/versioned_docs/version-2.2/k3d/explore/telemetry.mdx new file mode 100644 index 00000000..07395e53 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/telemetry.mdx @@ -0,0 +1,8 @@ +--- +title: Telemetry +sidebar_position: 8 +--- + +import ExploreTelemetry from "@site/docs/common/telemetry.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/explore/terraform.mdx b/versioned_docs/version-2.2/k3d/explore/terraform.mdx new file mode 100644 index 00000000..e89177d9 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/terraform.mdx @@ -0,0 +1,8 @@ +--- +title: Terraform & Atlantis +sidebar_position: 5 +--- + +import ExploreTerraform from "@site/docs/common/terraform.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/explore/user-creation.mdx b/versioned_docs/version-2.2/k3d/explore/user-creation.mdx new file mode 100644 index 00000000..2df1c0ec --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/user-creation.mdx @@ -0,0 +1,19 @@ +--- +title: User Creation +sidebar_position: 6 +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; + +import GitHubUserCreation from '@site/docs/civo/partials/github/_user-creation.mdx' +import GitLabUserCreation from '@site/docs/civo/partials/gitlab/_user-creation.mdx' + + + + + + + + + \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/explore/vault.mdx b/versioned_docs/version-2.2/k3d/explore/vault.mdx new file mode 100644 index 00000000..adb0126a --- /dev/null +++ b/versioned_docs/version-2.2/k3d/explore/vault.mdx @@ -0,0 +1,8 @@ +--- +title: Vault +sidebar_position: 7 +--- + +import ExploreVault from "@site/docs/common/vault.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/faq.mdx b/versioned_docs/version-2.2/k3d/faq.mdx new file mode 100644 index 00000000..be3487f7 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/faq.mdx @@ -0,0 +1,12 @@ +--- +hide_title: true +sidebar_label: FAQ +sidebar_position: 3 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: frequently asked quesitons about the kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import FAQ from "@site/docs/common/faq.mdx" + + diff --git a/versioned_docs/version-2.2/k3d/overview.mdx b/versioned_docs/version-2.2/k3d/overview.mdx new file mode 100644 index 00000000..f0967e36 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/overview.mdx @@ -0,0 +1,76 @@ +--- +hide_title: true +sidebar_label: Overview +sidebar_position: 1 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: an overview of the kubefirst platform +image: "https://docs.kubefirst.io/img/logo.svg" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + +
+
+ +
+
+ +import GitHubOverview from '@site/docs/k3d/partials/github/_overview.mdx' +import GitLabOverview from '@site/docs/k3d/partials/gitlab/_overview.mdx' + + + +# Overview + +The k3d provisioning process will: +- create a multinode k3d kubernetes cluster on your localhost + +- create a gitops git repository from our gitops-template, customized for you, and store it in your git provider +- install argocd and register it with your gitops repo so that your main branch powers the platform +- install all the platform apps using argocd gitops preconfigured sync waves (gitops repo `/registry` folder) +- apply terraform to configure Vault (gitops repo `/terraform/vault` folder) +- bind a webhook to atlantis to automate terraform executions +- integrate argo workflows with your git provider +- install argo workflow automation to build containers, publish charts, and provide gitops delivery pipelines +- install a sample app git repository that uses this automation to demonstrate gitops app delivery and promotion (metaphor repo) + +![kubefirst k3d with GitHub Cluster Diagram](../img/local/github/installation-diagram-light.png#light-mode)![kubefirst k3d with GitHub Cluster Diagram](../img/local/github/installation-diagram-dark.png#dark-mode) + +# Applications + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/k3d/partials/github/_install.mdx b/versioned_docs/version-2.2/k3d/partials/github/_install.mdx new file mode 100644 index 00000000..7dc04513 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/github/_install.mdx @@ -0,0 +1,94 @@ +# Local Platform Installation + +`kubefirst` is the name of our CLI that installs the platform of the same name to your local or cloud environment. + +## Prerequisites + +### Local Prerequisites + +If you are on macOS, and have [Homebrew](https://brew.sh) installed, you can run: + +```shell +brew install kubefirst/tools/kubefirst +``` + +To upgrade an existing kubefirst CLI to the latest version run: + +```shell +brew update +brew upgrade kubefirst +``` + +There are other ways to install kubefirst for different operating systems, architectures, and containerized environments. See our [installation README](https://github.com/kubefirst/kubefirst/blob/main/build/README.md) for details. + +### Docker Desktop + +[Install](https://docs.docker.com/get-docker/) Docker Desktop. + +### GitHub +Create or use an actual [GitHub](https://github.com) personal account + +### Install the CA (Certificate Authority) of mkcert in your trusted store + +We use [mkcert](https://github.com/FiloSottile/mkcert) to generate local certificates and serve `https` with the Traefik Ingress Controller. During the installation, kubefirst generates these certificates and pushes them to Kubernetes as secrets to attach to Ingress resources. + +To allow the applications running in your kubefirst platform in addition to your browser to trust the certificates generated by your kubefirst local install, you need to install the CA (Certificate Authority) of mkcert in your trusted store. To do so, follow these simple steps: + +```shell +brew install mkcert +mkcert -install +``` + +This is not an optional step: the cluster creation will fail if you don't install the mkcert CA in your trusted store. + +## Create your new local cluster + +To create a new kubefirst cluster locally, run + +```shell +kubefirst k3d create +``` + +Details about your execution will be logged to your `~/.k1/logs` directory. More information on `kubefirst k3d`, including optional flags, can be discovered by running `kubefirst k3d help`. + +We are able to create an ephemeral GitHub token that expires after 8 hours using a process that will prompt your browser to request access to your account. If you need a quick environment, this is a frictionless approach. However, if you need this environment for longer than 8 hours, which is probably the case, please follow our [GitHub Token Guide](../../../common/git-auth.mdx) and export a more permanent token to your terminal by using the following command: + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxx +``` + +When Docker is provided 5 GB of memory and 5 CPUs, the local kubefirst platform will provision in about 6 minutes and deprovision in about 1 minute. + +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../../overview.mdx). + +## After installation + +After the ~5 minute installation, your browser will open a new browser tab at completion with the Console UI at [https://kubefirst.kubefirst.dev](https://kubefirst.kubefirst.dev) to provide you an easy way to navigate through the different services that were provisioned. + +## Console UI Screen + +![kubefirst console screen](../../../img/common/github/console.png) + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/local/github/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst k3d root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +You will be automatically connected to your new Kubernetes cluster. To view all cluster pods, run + +```bash +kubectl get pods -A +``` \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/partials/github/_overview.mdx b/versioned_docs/version-2.2/k3d/partials/github/_overview.mdx new file mode 100644 index 00000000..ccaa6bee --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/github/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst k3d create` provisions a local [k3d](https://k3d.io) Kubernetes cluster to host your cloud native environment locally. + +Your k3d cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitHub Action Runner Controller | GitHub Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Traefik Ingress Controller | Native k3d Ingress Controller | diff --git a/versioned_docs/version-2.2/k3d/partials/github/_repositories.mdx b/versioned_docs/version-2.2/k3d/partials/github/_repositories.mdx new file mode 100644 index 00000000..1ecdd374 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/github/_repositories.mdx @@ -0,0 +1,37 @@ + # GitHub Repositories + +The `kubefirst k3d create` command will create a `gitops` and `metaphor` repository in your personal GitHub account as shown here. + +![GitHub repositories](../../../img/common/github/repositories.png) + +## Repositories + +### `gitops` + +The `gitops` repository houses all of our IAC and all our GitOps configurations. All of the infrastructure and application configuration that are installed with kubefirst were produced by some combination of Terraform and Argo CD in the `gitops` repository. You will add to this repository to extend your infrastructure or add new applications. + +### `metaphor` + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## Management + +If you need additional GitHub repositories, add a new section of Terraform code to `k3d-github/terraform/github/repos.tf` in your new `gitops` repository: + +```terraform +module "your_repo_name" { + source = "./modules/repository" + visibility = "private" + repo_name = "your_repo_name" + archive_on_destroy = false + auto_init = false # set to false if importing an existing repository +} +``` + +GitHub's Terraform provider give you access to [many more configuration options](https://registry.terraform.io/providers/integrations/github/latest/docs) than just these settings. + +## Making Changes with Terraform + +To make infrastructure and configuration changes with Terraform, simply open a pull request in the `gitops` repository. Your pull request will automatically provide plans, state locks, and applies, and even comment in the pull request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +![Atlantis Example on GitHub](../../../img/common/github/atlantis.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/partials/github/_user-creation.mdx b/versioned_docs/version-2.2/k3d/partials/github/_user-creation.mdx new file mode 100644 index 00000000..9450dbba --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/github/_user-creation.mdx @@ -0,0 +1,72 @@ +In this tutorial we will show how to add users to your local cluster through [Atlantis](https://www.runatlantis.io/), which will allow a preview of how changes made will be expressed through Terraform before branches are merged into your repository. + +Navigate to the `gitops` repository in your personal GitHub account, clone the contents, and create a new branch: + +```shell +cd gitops +git checkout -b new-user +``` + +The folder `k3d-github/terraform/users/admins` contains two separate files that represent admin users: `admin-one.tf` (commented-out), and the `kubefirst_bot` user. Here's the module from `admin-one.tf`: + +```terraform +module "admin_one" { + source = "./modules/user/github" + + acl_policies = ["admin"] + email = "your.admin@your-company.io" + first_name = "Admin" + github_username = "admin_one_github_username" + last_name = "One" + username = "aone" + user_disabled = false + userpass_accessor = data.vault_auth_backend.userpass.accessor +} +``` + +Uncomment and edit this code to replace the values for the `email`, `first_name`, `github_username`, `last_name`, and `username`. + +Then at the top of the same file `terraform/users/admins/admin-one.tf`. You should see one line of code commented with the `admin_one` user, please uncomment this line to look as follows: + +```terraform +resource "vault_identity_group_member_entity_ids" "admins_membership" { + member_entity_ids = [ + module.kbot.vault_identity_entity_id + , module.admin_one.vault_identity_entity_id # <- this line used to be commented + ] + + group_id = data.vault_identity_group.admins.group_id +} +``` + +```shell +git add . +git commit -m feat: add new user +git push --set-upstream origin new-user +``` + +Now, create a pull request. This will kick off the Atlantis workflow. Within a minute or so, a comment will appear on the pull request that shows the Terraform plan with the changes it will be making to your infrastructure. + +New plans can be requested on demand by commenting `atlantis plan` on your pull request. + +![Atlantis Plan Comment Example](../../../img/common/github/atlantis-comments.png) + +To apply these changes, you or someone in the organization can submit a comment on that pull request with the following text: `atlantis apply`. Doing so will instruct Atlantis to apply the plan. It will report back with the results within a minute or so. + +> Atlantis merges your Pull Request automatically once an apply is successfully executed. Don't merge Terraform pull requests yourself. Atlantis will always run plans automatically for you when a pull request is opened that changes files mapped in `atlantis.yaml`. + +Any new users you have created through this process will have their temporary initial passwords stored in your local [HashiCorp Vault](https://argocd.kubefirst.dev/applications/vault) cluster. You can also access Vault using the information provided to you in the terminal: you will find your users' individual initial passwords in the Vault secret store `/secrets/users/`. + +![vault token login](../../../img/kubefirst/local/vault-token-login.png) + +Once you've provided them their initial password, they can update it throughout the platform by modifying their user password entity in Vault. Anyone can change their own password, and admins can reset anyone's password. These rules, just like everything else on kubefirst, can be configured in your new `gitops` repository. + +![default user creation](../../../img/kubefirst/local/default-user-creation.png) + +The existence of a new user with your specified parameters demonstrates that you have successfully updated your users using Atlantis! + +### Troubleshooting Atlantis + +The free ngrok tunnel used for kubefirst local has a 2-hour expiration by default. In order to prevent this expiration from interfering with automated Atlantis executions, we have added an auto-rotating ngrok tunnel CronJob to the Atlantis namespace. The job will rotate the ngrok tunnel automatically register the new ngrok URL with your Atlantis secrets in Vault and your `gitops`repository webhook. + +Atlantis works by sending a webhooks to Atlantis from your `gitops` repository. If you're not receiving Terraform plan comments, check the webhooks section of your `gitops` repository settings and review the responses from the sent webhook requests. \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/partials/gitlab/_install.mdx b/versioned_docs/version-2.2/k3d/partials/gitlab/_install.mdx new file mode 100644 index 00000000..ddb6f40a --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/gitlab/_install.mdx @@ -0,0 +1,103 @@ +# Local Platform Installation with GitLab + +`kubefirst` is the name of our CLI that installs the platform of the same name to your local or cloud environment. + +![kubefirst k3d with GitLab Cluster Diagram](../../../img/local/gitlab/installation-diagram-light.png#light-mode)![kubefirst k3d with GitLab Cluster Diagram](../../../img/local/gitlab/installation-diagram-dark.png#dark-mode) + +## Prerequisites + +### Local Prerequisites + +If you are on macOS, and have [Homebrew](https://brew.sh) installed, you can run: + +```shell +brew install kubefirst/tools/kubefirst +``` + +To upgrade an existing kubefirst CLI to the latest version run: + +```shell +brew update +brew upgrade kubefirst +``` + +There are other ways to install kubefirst for different operating systems, architectures, and containerized environments. See our [installation README](https://github.com/kubefirst/kubefirst/blob/main/build/README.md) for details. + +### Docker Desktop + +[Install](https://docs.docker.com/get-docker/) Docker Desktop. + +### GitLab + +- Create or use an existing [GitLab account](https://gitlab.com). +- Create a [GitLab group](https://docs.gitlab.com/ee/user/group/) developer permissions. + +> GitLab SaaS offering has limitations that require us to use groups contrary to GitHub which can be use without an organization. + +### Install the CA (Certificate Authority) of mkcert in your trusted store + +We use [mkcert](https://github.com/FiloSottile/mkcert) to generate local certificates and serve `https` with the Traefik Ingress Controller. During the installation, kubefirst generates these certificates and pushes them to Kubernetes as secrets to attach to Ingress resources. + +To allow the applications running in your kubefirst platform in addition to your browser to trust the certificates generated by your kubefirst local install, you need to install the CA (Certificate Authority) of mkcert in your trusted store. To do so, follow these simple steps: + +```shell +brew install mkcert +mkcert -install +``` + +This is not an optional step: the cluster creation will fail if you don't install the mkcert CA in your trusted store. + +## Create your new local cluster + +To create a new kubefirst cluster locally, run + +```shell +kubefirst k3d create \ + --git-provider gitlab \ + --gitlab-group your-group \ + --cluster-name kubefirst +``` + +Details about your execution will be logged to your `~/.k1/logs` directory. More information on `kubefirst k3d`, including optional flags, can be discovered by running `kubefirst k3d help`. + +We are able to create an ephemeral GitLab token that expires after 8 hours using a process that will prompt your browser to request access to your account. If you need a quick environment, this is a frictionless approach. However, if you need this environment for longer than 8 hours, which is probably the case, please follow our [GitHub Token Guide](../../../common/git-auth.mdx) and export a more permanent token to your terminal by using the following command: + +```shell +export GITLAB_TOKEN=gl_xxxxxxxx +``` + +When Docker is provided 5 GB of memory and 5 CPUs, the local kubefirst platform will provision in about 6 minutes and deprovision in about 1 minute. + +### Installed Applications + +To see what is installed by kubefirst, check the [overview page](../../overview.mdx). + +## After installation + +After the ~5 minute installation, your browser will open a new browser tab at completion with the Console UI at [https://kubefirst.kubefirst.dev](https://kubefirst.kubefirst.dev) to provide you an easy way to navigate through the different services that were provisioned. + +## Console UI Screen + +![kubefirst console screen](../../../img/common/gitlab/console.png) + +## Example of terminal output following cluster creation + +![terminal handoff](../../../img/local/gitlab/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst k3d root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +## Connecting to Kubernetes + +You will be automatically connected to your new Kubernetes cluster. To view all cluster pods, run + +```bash +kubectl get pods -A +``` \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/partials/gitlab/_overview.mdx b/versioned_docs/version-2.2/k3d/partials/gitlab/_overview.mdx new file mode 100644 index 00000000..03cf42ff --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/gitlab/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst k3d create` provisions a local [k3d](https://k3d.io) Kubernetes cluster to host your cloud native environment locally. + +Your k3d cluster will include: + +| Application | Description | +|---------------------------------|-----------------------------------------------------------------------------| +| Argo CD | GitOps Continuous Delivery | +| Argo Workflows | Application Continuous Integration | +| Atlantis | Terraform Workflow Automation | +| cert-manager | Certificate Automation Utility | +| ChartMuseum | Helm Chart Registry | +| External Secrets Operators | Syncs Kubernetes secrets with Vault secrets | +| GitLab Runner | GitLab Self-Hosted CI Executor | +| HashiCorp Vault | Secrets Management | +| Metaphor | (development, staging, production) instance of sample Next.js app | +| Traefik Ingress Controller | Native k3d Ingress Controller | diff --git a/versioned_docs/version-2.2/k3d/partials/gitlab/_repositories.mdx b/versioned_docs/version-2.2/k3d/partials/gitlab/_repositories.mdx new file mode 100644 index 00000000..0d60f6ef --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/gitlab/_repositories.mdx @@ -0,0 +1,40 @@ +# GitLab Repositories + +The `kubefirst k3d create` command will create a `gitops` and `metaphor` repository in your personal GitLab account as shown here. + +![GitLab repositories](../../../img/common/gitlab/repositories.png) + +## Repositories + +### `gitops` + +The `gitops` repository houses all of our IAC and all our GitOps configurations. All of the infrastructure and application configuration that you receive with kubefirst was produced by some combination of Terraform and Argo CD in the `gitops` repository. You will add to this repository as extend your infrastructure or new applications. + +### `metaphor` + +`metaphor` is a suite of demo microservice applications to demonstrate how an application can be integrated into the kubefirst platform following best practices. It is described in more details [here](../../../common/metaphor.mdx). + +## Management + +As you need additional GitLab repositories, just add a new section of Terraform code to `terraform/gitlab/repos.tf` in your new `gitops` repository: + +```terraform +# set auto_init to false if importing an existing repository +# true if it's a new repository + +module "your_repo_name" { + source = "./modules/repository" + visibility = "private" + repo_name = "your-repo-name" + archive_on_destroy = true + auto_init = false +} +``` + +GitLab's Terraform provider provides [more configuration options](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) than just these settings. + +## Making Terraform Changes + +To make infrastructure and configuration changes with Terraform, simply open a merge request in the `gitops` repository. Your merge request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes. + +![Atlantis Example on GitLab](../../../img/common/github/atlantis.png) \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/partials/gitlab/_user-creation.mdx b/versioned_docs/version-2.2/k3d/partials/gitlab/_user-creation.mdx new file mode 100644 index 00000000..0b6d0b23 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/partials/gitlab/_user-creation.mdx @@ -0,0 +1,77 @@ +In this tutorial we will show how to add users to your local cluster through [Atlantis](https://www.runatlantis.io/), which will allow a preview of how changes made will be expressed through Terraform before branches are merged into your repository. + +Navigate to the `gitops` repository in your personal GitLab account, clone the contents, and create a new branch: + +```shell +cd gitops +git checkout -b new-user +``` + +The file `terraform/users/admins/admin-one.tf` contains a block that represents a new admin user: + +```terraform +module "admin_one" { + source = "../modules/user" + + acl_policies = ["admin"] + email = "your.admin@your-company.io" + first_name = "Admin" + fullname = "Admin One" + group_id = data.vault_identity_group.admins.group_id + gitlab_username = "your-admins-gitlab-username" + last_name = "One" + username = "aone" + user_disabled = false + userpass_accessor = data.vault_auth_backend.userpass.accessor +} + +``` + +Uncomment and edit this code to replace the values for the `email`, `first_name`, `github_username`, `last_name`, `full_name` and `username`. + +Then navigate to the file `terraform/users/admins/admin-one.tf`. You should see one line of code commented with the `admin_one` user, please uncomment this line to look as follows: + +```terraform +# every admin that is added to the platform will need to have their ID +# added to this list so that its client id is added to the group in Vault +output "vault_identity_entity_ids" { + value = [ + module.kbot.vault_identity_entity_id, + module.admin_one.vault_identity_entity_id, # <- this line used to be commented + ] +} +``` + +Now let's commit and push your change + +```shell +git add . +git commit -m feat: add new user +git push --set-upstream origin new-user +``` + +Now, create a merge request. This will kick off the Atlantis workflow. Within a minute or so, a comment will appear on the merge request that shows the Terraform plan with the changes it will be making to your infrastructure. + +New plans can be requested on demand by commenting `atlantis plan` on your merge request. + +![Atlantis comments example](../../../img/common/gitlab/atlantis-comments.png) + +To apply these changes, you or someone in the organization can submit a comment on that merge request with the following text: `atlantis apply`. Doing so will instruct Atlantis to apply the plan. It will report back with the results within a minute or so. + +> Atlantis merges your merge request automatically once an apply is successfully executed. Don't merge Terraform merge requests yourself. Atlantis will always run plans automatically for you when a merge request is opened that changes files mapped in `atlantis.yaml`. + +Any new users you have created through this process will have their temporary initial passwords stored in your local [HashiCorp Vault](https://argocd.kubefirst.dev/applications/vault) cluster. You can also access Vault using the information provided to you in the terminal: you will find your users' individual initial passwords in the Vault secret store `/secrets/users/`. + +![vault token login](../../../img/kubefirst/local/vault-token-login.png) + +Once you've provided them their initial password, they can update it throughout the platform by modifying their user password entity in Vault. Anyone can change their own password, and admins can reset anyone's password. These rules, just like everything else on kubefirst, can be configured in your new `gitops` repository. + +![default user creation](../../../img/kubefirst/local/default-user-creation.png) + +The existence of a new user with your specified parameters demonstrates that you have successfully updated your users using Atlantis! + +### Troubleshooting Atlantis + +The free ngrok tunnel used for kubefirst local has a 2-hour expiration by default. In order to prevent this expiration from interfering with automated Atlantis executions, we have added an auto-rotating ngrok tunnel CronJob to the Atlantis namespace. The job will rotate the ngrok tunnel automatically register the new ngrok URL with your Atlantis secrets in Vault and your `gitops` repository webhook. + +Atlantis works by sending a webhooks to Atlantis from your `gitops` repository. If you're not receiving Terraform plan comments, check the webhooks section of your `gitops` repository settings and review the responses from the sent webhook requests. \ No newline at end of file diff --git a/versioned_docs/version-2.2/k3d/quick-start/install.mdx b/versioned_docs/version-2.2/k3d/quick-start/install.mdx new file mode 100644 index 00000000..bd333f01 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/quick-start/install.mdx @@ -0,0 +1,55 @@ +--- +hide_title: true +sidebar_label: Install +sidebar_position: 2 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + + +
+
+ +
+
+ +import GitHubInstall from '@site/docs/k3d/partials/github/_install.mdx' +import GitLabInstall from '@site/docs/k3d/partials/gitlab/_install.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/k3d/quick-start/repositories.mdx b/versioned_docs/version-2.2/k3d/quick-start/repositories.mdx new file mode 100644 index 00000000..24189053 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/quick-start/repositories.mdx @@ -0,0 +1,56 @@ +--- +hide_title: true +sidebar_label: Repositories +sidebar_position: 3 +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +image: "https://docs.kubefirst.io/img/logo.svg" +--- +--- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import styles from "@site/docs/stylesheets/tabs.module.css"; +import ReactDom from 'react-dom' +import * as config from "@site/docs/constants.js" + + +
+
+ +
+
+ +import GitHubRepositories from '@site/docs/k3d/partials/github/_repositories.mdx' +import GitLabRepositories from '@site/docs/k3d/partials/gitlab/_repositories.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/versioned_docs/version-2.2/k3d/quick-start/styles.module.css b/versioned_docs/version-2.2/k3d/quick-start/styles.module.css new file mode 100644 index 00000000..a6e39ce9 --- /dev/null +++ b/versioned_docs/version-2.2/k3d/quick-start/styles.module.css @@ -0,0 +1,13 @@ +.gitlab { +color: #fc6d26; +} +.gitlab[aria-selected='true'] { +border-bottom-color: #fc6d26; +} + +.github { +color: black; +} +.github[aria-selected='true'] { +border-bottom-color: black; +} \ No newline at end of file diff --git a/versioned_docs/version-2.2/stylesheets/extra.css b/versioned_docs/version-2.2/stylesheets/extra.css new file mode 100644 index 00000000..09dfabb1 --- /dev/null +++ b/versioned_docs/version-2.2/stylesheets/extra.css @@ -0,0 +1,21 @@ +:root > * { + --md-primary-fg-color: #3C356C; + --md-primary-fg-color--light: #DF6D5D; + --md-primary-fg-color--dark: #81E2B4; +} + +.md-typeset table:not([class]) { + border: 0; +} + +[dir=ltr] .md-typeset ol li, [dir=ltr] .md-typeset ul li { + margin-bottom: 0; +} + +[dir=ltr] .md-typeset ol, [dir=ltr] .md-typeset ul { + padding-left: 1.25em; +} + +.md-typeset a { + color: #8851C8 !important; +} \ No newline at end of file diff --git a/versioned_docs/version-2.2/stylesheets/tabs.module.css b/versioned_docs/version-2.2/stylesheets/tabs.module.css new file mode 100644 index 00000000..ec49112e --- /dev/null +++ b/versioned_docs/version-2.2/stylesheets/tabs.module.css @@ -0,0 +1,15 @@ +.gitlab { + color: #fc6d26; +} + +.gitlab[aria-selected="true"] { + border-bottom-color: #fc6d26; +} + +.github { + color: black; +} + +.github[aria-selected="true"] { + border-bottom-color: black; +} diff --git a/versioned_sidebars/version-2.2-sidebars.json b/versioned_sidebars/version-2.2-sidebars.json new file mode 100644 index 00000000..3592b205 --- /dev/null +++ b/versioned_sidebars/version-2.2-sidebars.json @@ -0,0 +1,80 @@ +{ + "aws": [ + "aws/overview", + { + "Quick Start": [ + { + "Install": [ + { + "type": "autogenerated", + "dirName": "aws/quick-start/install" + } + ] + }, + "aws/quick-start/repositories" + ], + "Explore": [ + { + "type": "autogenerated", + "dirName": "aws/explore" + } + ], + "Advanced": [ + { + "type": "autogenerated", + "dirName": "aws/advanced" + } + ] + }, + "civo/gitops-catalog", + "aws/deprovision", + "aws/faq", + "aws/credits" + ], + "civo": [ + "civo/overview", + { + "Quick Start": [ + { + "Install": [ + { + "type": "autogenerated", + "dirName": "civo/quick-start/install" + } + ] + }, + "civo/quick-start/repositories" + ], + "Explore": [ + { + "type": "autogenerated", + "dirName": "civo/explore" + } + ] + }, + "civo/gitops-catalog", + "civo/deprovision", + "civo/faq", + "civo/credits" + ], + "k3d": [ + "k3d/overview", + { + "Quick Start": [ + { + "type": "autogenerated", + "dirName": "k3d/quick-start" + } + ], + "Explore": [ + { + "type": "autogenerated", + "dirName": "k3d/explore" + } + ] + }, + "k3d/deprovision", + "k3d/faq", + "k3d/credits" + ] +} diff --git a/versions.json b/versions.json index ce72ad22..1d8ff6fd 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "2.2", "2.1", "2.0" ]