diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 837acf55..a9bd1350 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -111,7 +111,7 @@ In MDX v1, JSX and Markdown don't interoperate well: it has been fixed in MDX v2 ##### Admonitions -You can also use special Docusaurus Markdown syntax called admonitions, which let you display beautiful notes, informations, warnings, and others. +You can also use special Docusaurus Markdown syntax called admonitions, which let you display beautiful notes, information, warnings, and others. ```markdown :::note diff --git a/docs/constants.js b/docs/constants.js index e1ed0f78..15a2edd9 100644 --- a/docs/constants.js +++ b/docs/constants.js @@ -10,3 +10,5 @@ export const GITLAB_LOGO_URL = 'https://assets.kubefirst.com/console/gitlab.svg'; export const VULTR_LOGO_URL = 'https://cf-assets.www.cloudflare.com/slt3lc6tev37/1ATBPX4YOBbCRkybT4zS2e/f4f5f0900b57c61e65960efb3d11c64f/Vultr_logo_high_res.png'; +export const GCP_LOGO_URL = + 'https://upload.wikimedia.org/wikipedia/commons/5/51/Google_Cloud_logo.svg'; diff --git a/docs/gcp/credits.mdx b/docs/gcp/credits.mdx new file mode 100644 index 00000000..11475ce6 --- /dev/null +++ b/docs/gcp/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" + + diff --git a/docs/gcp/deprovision.mdx b/docs/gcp/deprovision.mdx new file mode 100644 index 00000000..e9a1ba15 --- /dev/null +++ b/docs/gcp/deprovision.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +display_sidebar: gcp +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/docs/gcp/explore/argocd.mdx b/docs/gcp/explore/argocd.mdx new file mode 100644 index 00000000..9f4f59f0 --- /dev/null +++ b/docs/gcp/explore/argocd.mdx @@ -0,0 +1,8 @@ +--- +title: Argo CD +sidebar_position: 1 +--- + +import ExploreArgocd from "@site/docs/common/argocd.mdx" + + diff --git a/docs/gcp/explore/gitops.mdx b/docs/gcp/explore/gitops.mdx new file mode 100644 index 00000000..b1ac43cd --- /dev/null +++ b/docs/gcp/explore/gitops.mdx @@ -0,0 +1,9 @@ +--- +title: GitOps +sidebar_position: 2 +--- + + +import ExploreGitOps from "@site/docs/common/gitops.mdx" + + diff --git a/docs/gcp/explore/metaphor.mdx b/docs/gcp/explore/metaphor.mdx new file mode 100644 index 00000000..6ff78d11 --- /dev/null +++ b/docs/gcp/explore/metaphor.mdx @@ -0,0 +1,8 @@ +--- +title: Metaphor +sidebar_position: 3 +--- + +import ExploreMetaphor from "@site/docs/common/metaphor.mdx" + + diff --git a/docs/gcp/explore/telemetry.mdx b/docs/gcp/explore/telemetry.mdx new file mode 100644 index 00000000..dfebeac8 --- /dev/null +++ b/docs/gcp/explore/telemetry.mdx @@ -0,0 +1,8 @@ +--- +title: Telemetry +sidebar_position: 7 +--- + +import ExploreTelemetry from "@site/docs/common/telemetry.mdx" + + diff --git a/docs/gcp/explore/terraform.mdx b/docs/gcp/explore/terraform.mdx new file mode 100644 index 00000000..cfdd1f88 --- /dev/null +++ b/docs/gcp/explore/terraform.mdx @@ -0,0 +1,8 @@ +--- +title: Terraform & Atlantis +sidebar_position: 4 +--- + +import ExploreTerraform from "@site/docs/common/terraform.mdx" + + diff --git a/docs/gcp/explore/user-creation.mdx b/docs/gcp/explore/user-creation.mdx new file mode 100644 index 00000000..26117629 --- /dev/null +++ b/docs/gcp/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/gcp/partials/github/_user-creation.mdx' +import GitLabUserCreation from '@site/docs/gcp/partials/gitlab/_user-creation.mdx' + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/docs/gcp/explore/vault.mdx b/docs/gcp/explore/vault.mdx new file mode 100644 index 00000000..49695f4a --- /dev/null +++ b/docs/gcp/explore/vault.mdx @@ -0,0 +1,8 @@ +--- +title: Vault +sidebar_position: 6 +--- + +import ExploreVault from "@site/docs/common/vault.mdx" + + diff --git a/docs/gcp/faq.mdx b/docs/gcp/faq.mdx new file mode 100644 index 00000000..55bb58eb --- /dev/null +++ b/docs/gcp/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/docs/gcp/overview.mdx b/docs/gcp/overview.mdx new file mode 100644 index 00000000..002d5f0a --- /dev/null +++ b/docs/gcp/overview.mdx @@ -0,0 +1,62 @@ +--- +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 Google Cloud 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/gcp/partials/github/_overview.mdx' +import GitLabOverview from '@site/docs/gcp/partials/gitlab/_overview.mdx' +import CloudBanner from '@site/src/components/CloudBanner/CloudBanner.jsx' +import CommonProvisionProcess from "@site/docs/common/partials/common/_provision-process.mdx"; + + + +# Overview + +:::caution + +Google Cloud is in beta. Use at your own risks. + +::: + +The Google Cloud provisioning process will: + + +![kubefirst Google Cloud with GitLab Cluster Diagram](../img/gcp/gitlab/installation-diagram-light.png#light-mode)![kubefirst Google Cloud with GitLab Cluster Diagram](../img/gcp/gitlab/installation-diagram-dark.png#dark-mode) + +# Applications + + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/docs/gcp/partials/common/_cluster-connectivity.mdx b/docs/gcp/partials/common/_cluster-connectivity.mdx new file mode 100644 index 00000000..8ef8fac6 --- /dev/null +++ b/docs/gcp/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/docs/gcp/partials/common/_installed-applications.mdx b/docs/gcp/partials/common/_installed-applications.mdx new file mode 100644 index 00000000..3a8283c0 --- /dev/null +++ b/docs/gcp/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/docs/gcp/partials/common/_prerequisites.mdx b/docs/gcp/partials/common/_prerequisites.mdx new file mode 100644 index 00000000..a5b1e1c0 --- /dev/null +++ b/docs/gcp/partials/common/_prerequisites.mdx @@ -0,0 +1,13 @@ +## Prerequisites + +### Local Prerequisites + +[Install](../../overview.mdx) the kubefirst CLI. + +### Google Cloud Prerequisites + +For kubefirst to be able to provision your Google Cloud resources: + +- A [Google Cloud account](https://cloud.google.com) in which you are an account owner. +- A publicly routable [DNS](https://cloud.google.com/dns/docs/overview). +- A [Google Cloud token](https://console.cloud.google.com/apis/credentials). diff --git a/docs/gcp/partials/common/_root-credentials-cmd.mdx b/docs/gcp/partials/common/_root-credentials-cmd.mdx new file mode 100644 index 00000000..825f2f9c --- /dev/null +++ b/docs/gcp/partials/common/_root-credentials-cmd.mdx @@ -0,0 +1,12 @@ +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst beta gcp root-credentials +``` + +![terminal handoff](../../../img/common/kubefirst/root-credentials.png) + +:::note the `kubefirst beta gcp root-credentials` command was introduced in 2.0.1 +::: diff --git a/docs/gcp/partials/github/_cluster-create.mdx b/docs/gcp/partials/github/_cluster-create.mdx new file mode 100644 index 00000000..bc483bf8 --- /dev/null +++ b/docs/gcp/partials/github/_cluster-create.mdx @@ -0,0 +1,22 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Google Cloud tokens in addition to the appropriate values for your new platform. + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx +export gcp_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +kubefirst beta gcp 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 Google Cloud 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/gcp/gitlab/handoff-screen.png) diff --git a/docs/gcp/partials/github/_install.mdx b/docs/gcp/partials/github/_install.mdx new file mode 100644 index 00000000..dfe30a5d --- /dev/null +++ b/docs/gcp/partials/github/_install.mdx @@ -0,0 +1,76 @@ +# Google Cloud 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. + +### Google Cloud Prerequisites + +For kubefirst to be able to provision your Google Cloud resources: + +- A [Google Cloud account](https://cloud.google.com) in which you are an account owner. +- A publicly routable [DNS](https://cloud.google.com/dns/docs/overview). +- Generate [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials#GAC) (ADC) (you could use the [Google Cloud CLI](https://cloud.google.com/sdk/gcloud) with the command `gcloud auth application-default login`) + +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Google Cloud credentials file path (it's set to the default for macOS in the code example below) in addition to the appropriate values for your new platform. + +```shell +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx +export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json + +kubefirst beta gcp 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 Google Cloud 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/gcp/github/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst beta gcp 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). diff --git a/docs/gcp/partials/github/_overview.mdx b/docs/gcp/partials/github/_overview.mdx new file mode 100644 index 00000000..79a6aa9f --- /dev/null +++ b/docs/gcp/partials/github/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst beta gcp create` provisions a local [Google Cloud](https://cloud.google.com) Kubernetes cluster to host your cloud native environment locally. + +Your Google Cloud 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/docs/gcp/partials/github/_prerequisites.mdx b/docs/gcp/partials/github/_prerequisites.mdx new file mode 100644 index 00000000..748f4a36 --- /dev/null +++ b/docs/gcp/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/docs/gcp/partials/github/_repositories.mdx b/docs/gcp/partials/github/_repositories.mdx new file mode 100644 index 00000000..4fb14ca7 --- /dev/null +++ b/docs/gcp/partials/github/_repositories.mdx @@ -0,0 +1,25 @@ +# GitHub Repositories + +When you deploy a cluster on Google Cloud 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 `gcp-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/docs/gcp/partials/github/_user-creation.mdx b/docs/gcp/partials/github/_user-creation.mdx new file mode 100644 index 00000000..104f75c0 --- /dev/null +++ b/docs/gcp/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 `gcp-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. diff --git a/docs/gcp/partials/gitlab/_cluster-create.mdx b/docs/gcp/partials/gitlab/_cluster-create.mdx new file mode 100644 index 00000000..5c87f7bf --- /dev/null +++ b/docs/gcp/partials/gitlab/_cluster-create.mdx @@ -0,0 +1,15 @@ +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Google Cloud tokens in addition to the appropriate values for your new platform. + +```shell +export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx +export gcp_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +kubefirst beta gcp 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/docs/gcp/partials/gitlab/_install.mdx b/docs/gcp/partials/gitlab/_install.mdx new file mode 100644 index 00000000..17671173 --- /dev/null +++ b/docs/gcp/partials/gitlab/_install.mdx @@ -0,0 +1,80 @@ +# Google Cloud 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. + +### Google Cloud + +For kubefirst to be able to provision your Google Cloud resources: + +- A [Google Cloud account](https://cloud.google.com) in which you are an account owner. +- A publicly routable [DNS](https://cloud.google.com/dns/docs/overview). +- Generate [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials#GAC) (ADC) (you could use the [Google Cloud CLI](https://cloud.google.com/sdk/gcloud) with the command `gcloud auth application-default login`) + +## Create your new kubefirst cluster + +Adjust the following command with your GitHub and Google Cloud credentials file path (it's set to the default for macOS in the code example below) in addition to the appropriate values for your new platform. + +```shell +export GITLAB_TOKEN=xxxxxxxxxxxxxxxx +export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json + +kubefirst beta gcp 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 Google Cloud 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/gcp/gitlab/handoff-screen.png) + +## Root credentials + +To obtain your 3 initial passwords, run + +```bash +kubefirst beta gcp 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). diff --git a/docs/gcp/partials/gitlab/_overview.mdx b/docs/gcp/partials/gitlab/_overview.mdx new file mode 100644 index 00000000..7780a73a --- /dev/null +++ b/docs/gcp/partials/gitlab/_overview.mdx @@ -0,0 +1,16 @@ +`kubefirst beta gcp create` provisions a local [Google Cloud](https://gcp.com) Kubernetes cluster to host your cloud native environment locally. + +Your Google Cloud 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/docs/gcp/partials/gitlab/_prerequisites.mdx b/docs/gcp/partials/gitlab/_prerequisites.mdx new file mode 100644 index 00000000..131880f2 --- /dev/null +++ b/docs/gcp/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. +::: diff --git a/docs/gcp/partials/gitlab/_repositories.mdx b/docs/gcp/partials/gitlab/_repositories.mdx new file mode 100644 index 00000000..79e8fc19 --- /dev/null +++ b/docs/gcp/partials/gitlab/_repositories.mdx @@ -0,0 +1,37 @@ +# GitLab Repositories + +When you install the Google Cloud 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` 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). + +## 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 `gcp-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/docs/gcp/partials/gitlab/_user-creation.mdx b/docs/gcp/partials/gitlab/_user-creation.mdx new file mode 100644 index 00000000..bf5fe9f7 --- /dev/null +++ b/docs/gcp/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 `gcp-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. diff --git a/docs/gcp/platform.mdx b/docs/gcp/platform.mdx new file mode 100644 index 00000000..67c8d66a --- /dev/null +++ b/docs/gcp/platform.mdx @@ -0,0 +1,11 @@ +--- +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" + + diff --git a/docs/gcp/quick-start/install/cli.mdx b/docs/gcp/quick-start/install/cli.mdx new file mode 100644 index 00000000..a3dd044f --- /dev/null +++ b/docs/gcp/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/gcp/partials/github/_cluster-create.mdx"; + +import GitLabPrerequisites from "@site/docs/common/partials/gitlab/_prerequisites.mdx"; +import GitLabClusterCreateCmd from "@site/docs/gcp/partials/gitlab/_cluster-create.mdx"; + +import CommonCloudPrerequisites from "@site/docs/gcp/partials/common/_prerequisites.mdx"; +import CommonClusterConnectivity from "@site/docs/gcp/partials/common/_cluster-connectivity.mdx"; +import CommonRootCredentialsCmd from "@site/docs/gcp/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/docs/gcp/quick-start/install/ui.mdx b/docs/gcp/quick-start/install/ui.mdx new file mode 100644 index 00000000..2c4d0f6e --- /dev/null +++ b/docs/gcp/quick-start/install/ui.mdx @@ -0,0 +1,76 @@ +--- +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. + +```shell +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install kubefirst --create-namespace kubefirst/kubefirst + +k 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 MongoDB to run on the ARM architecture. + +```shell +helm repo add kubefirst https://charts.kubefirst.com +helm repo update + +helm install 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 +``` + +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. + +```shell +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) diff --git a/docs/gcp/quick-start/repositories.mdx b/docs/gcp/quick-start/repositories.mdx new file mode 100644 index 00000000..ed00b05b --- /dev/null +++ b/docs/gcp/quick-start/repositories.mdx @@ -0,0 +1,55 @@ +--- +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/gcp/partials/github/_repositories.mdx' +import GitLabRepositories from '@site/docs/gcp/partials/gitlab/_repositories.mdx' + +
+
+ +
+
+ + + + + GitHub + + } + > + + + + + GitLab + + } + > + + + diff --git a/docs/gcp/quick-start/styles.module.css b/docs/gcp/quick-start/styles.module.css new file mode 100644 index 00000000..ec10699b --- /dev/null +++ b/docs/gcp/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/docs/img/gcp/github/handoff-screen.png b/docs/img/gcp/github/handoff-screen.png new file mode 100644 index 00000000..f9af36f0 Binary files /dev/null and b/docs/img/gcp/github/handoff-screen.png differ diff --git a/docs/img/gcp/github/installation-diagram-dark.png b/docs/img/gcp/github/installation-diagram-dark.png new file mode 100644 index 00000000..29073b48 Binary files /dev/null and b/docs/img/gcp/github/installation-diagram-dark.png differ diff --git a/docs/img/gcp/github/installation-diagram-light.png b/docs/img/gcp/github/installation-diagram-light.png new file mode 100644 index 00000000..21627db2 Binary files /dev/null and b/docs/img/gcp/github/installation-diagram-light.png differ diff --git a/docs/img/gcp/gitlab/handoff-screen.png b/docs/img/gcp/gitlab/handoff-screen.png new file mode 100644 index 00000000..f9af36f0 Binary files /dev/null and b/docs/img/gcp/gitlab/handoff-screen.png differ diff --git a/docs/img/gcp/gitlab/installation-diagram-dark.png b/docs/img/gcp/gitlab/installation-diagram-dark.png new file mode 100644 index 00000000..42368de2 Binary files /dev/null and b/docs/img/gcp/gitlab/installation-diagram-dark.png differ diff --git a/docs/img/gcp/gitlab/installation-diagram-light.png b/docs/img/gcp/gitlab/installation-diagram-light.png new file mode 100644 index 00000000..6c26255b Binary files /dev/null and b/docs/img/gcp/gitlab/installation-diagram-light.png differ diff --git a/docs/index.mdx b/docs/index.mdx index f88831d7..88970d1b 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -103,4 +103,23 @@ We support local, AWS, and Civo clouds, with additional clouds in beta. By runni +
+
+
+ Google Cloud +
+
+

Google Cloud

+

Google Cloud Platform, offered by Google, is a suite of cloud computing services that runs on the same infrastructure that Google uses internally for its end-user products, such as Google Search, Gmail, Google Drive, and YouTube.

+
+
+
+ +
+
+
+
diff --git a/docusaurus.config.js b/docusaurus.config.js index 4216d750..2e7c1671 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -131,6 +131,12 @@ const config = { sidebarId: 'vultr', label: 'Vultr', }, + { + type: 'docSidebar', + position: 'left', + sidebarId: 'gcp', + label: 'Google Cloud', + }, { type: 'docsVersionDropdown', position: 'right', diff --git a/sidebars.js b/sidebars.js index bcb72769..82efdcdf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -71,6 +71,31 @@ const sidebars = { 'civo/faq', 'civo/credits', ], + gcp: [ + 'gcp/overview', + { + 'Quick Start': [ + { + 'Install': [ + { + type: 'autogenerated', + dirName: 'gcp/quick-start/install', + } + ], + }, + 'gcp/quick-start/repositories', + ], + 'Explore': [ + { + type: 'autogenerated', + dirName: 'gcp/explore', + }, + ], + }, + 'gcp/deprovision', + 'gcp/faq', + 'gcp/credits', + ], k3d: [ 'k3d/overview', { diff --git a/static/img/gcp_header.png b/static/img/gcp_header.png new file mode 100644 index 00000000..e17c5453 Binary files /dev/null and b/static/img/gcp_header.png differ diff --git a/styles/Custom/ignore.txt b/styles/Custom/ignore.txt index 8d5aee15..43747ffc 100644 --- a/styles/Custom/ignore.txt +++ b/styles/Custom/ignore.txt @@ -22,6 +22,7 @@ eks # F # G +gcp github gitlab gitops diff --git a/styles/Custom/substitutions.yml b/styles/Custom/substitutions.yml index d3be10d4..f927f3b3 100644 --- a/styles/Custom/substitutions.yml +++ b/styles/Custom/substitutions.yml @@ -24,6 +24,8 @@ swap: ecr: ECR eks: EKS docker: Docker + gcp: Google Cloud + gcp cloud: Google Cloud # Starting or with a space before, and ending with a dot or space (so not working used in a path, caused of MDX) '[G|g]ithub': GitHub # Starting or with a space before, and ending with a dot or space (so not working used in a path, caused of MDX) diff --git a/styles/Vocab/base/accept.txt b/styles/Vocab/base/accept.txt index fe8c4451..bb7a96c3 100644 --- a/styles/Vocab/base/accept.txt +++ b/styles/Vocab/base/accept.txt @@ -1,4 +1,5 @@ # A +admunition anonymize auditable automation diff --git a/versioned_docs/version-2.0/gcp/upgrade.md b/versioned_docs/version-2.0/gcp/upgrade.md new file mode 100644 index 00000000..d264485c --- /dev/null +++ b/versioned_docs/version-2.0/gcp/upgrade.md @@ -0,0 +1,5 @@ +--- +title: Google Cloud +--- + +Google Cloud support was added in kubefirst 2.1.2, please upgrade your client to 2.1.2 or later to use this cloud provider. diff --git a/versioned_docs/version-2.1/gcp/upgrade.md b/versioned_docs/version-2.1/gcp/upgrade.md new file mode 100644 index 00000000..d264485c --- /dev/null +++ b/versioned_docs/version-2.1/gcp/upgrade.md @@ -0,0 +1,5 @@ +--- +title: Google Cloud +--- + +Google Cloud support was added in kubefirst 2.1.2, please upgrade your client to 2.1.2 or later to use this cloud provider. diff --git a/versioned_docs/version-2.2/gcp/upgrade.md b/versioned_docs/version-2.2/gcp/upgrade.md new file mode 100644 index 00000000..d264485c --- /dev/null +++ b/versioned_docs/version-2.2/gcp/upgrade.md @@ -0,0 +1,5 @@ +--- +title: Google Cloud +--- + +Google Cloud support was added in kubefirst 2.1.2, please upgrade your client to 2.1.2 or later to use this cloud provider. diff --git a/versioned_sidebars/version-2.0-sidebars.json b/versioned_sidebars/version-2.0-sidebars.json index 79d706c5..d8198ae8 100644 --- a/versioned_sidebars/version-2.0-sidebars.json +++ b/versioned_sidebars/version-2.0-sidebars.json @@ -198,5 +198,8 @@ ], "vultr": [ "kubefirst/vultr/upgrade" + ], + "gcp": [ + "gcp/upgrade" ] } diff --git a/versioned_sidebars/version-2.1-sidebars.json b/versioned_sidebars/version-2.1-sidebars.json index 5fc2f1e7..bfd86c65 100644 --- a/versioned_sidebars/version-2.1-sidebars.json +++ b/versioned_sidebars/version-2.1-sidebars.json @@ -77,5 +77,8 @@ ], "vultr": [ "vultr/upgrade" + ], + "gcp": [ + "gcp/upgrade" ] } diff --git a/versioned_sidebars/version-2.2-sidebars.json b/versioned_sidebars/version-2.2-sidebars.json index af4c0032..97c29217 100644 --- a/versioned_sidebars/version-2.2-sidebars.json +++ b/versioned_sidebars/version-2.2-sidebars.json @@ -79,5 +79,8 @@ ], "vultr": [ "vultr/upgrade" + ], + "gcp": [ + "gcp/upgrade" ] }