diff options
Diffstat (limited to 'doc/user/clusters')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_workflow.md | 42 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/flux.md | 6 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/flux_tutorial.md | 52 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/helm.md | 10 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/secrets_management.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/agent/index.md | 6 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 25 | ||||
| -rw-r--r-- | doc/user/clusters/agent/troubleshooting.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/agent/work_with_agent.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/cost_management.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/create/index.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/environments.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/integrations.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/management_project.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/management_project_template.md | 4 | ||||
| -rw-r--r-- | doc/user/clusters/migrating_from_gma_to_project_template.md | 4 |
17 files changed, 120 insertions, 65 deletions
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 982411d35f9..1ca558adbc2 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -1,13 +1,13 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Kubernetes cluster **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. -> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The pre-configured variable `$KUBECONFIG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. @@ -78,7 +78,8 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma - You can install additional agents into the same cluster to accommodate additional hierarchies. - You can authorize up to 100 projects. -All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +All CI/CD jobs now include a `kubeconfig` file with contexts for every shared agent connection. +The `kubeconfig` path is available in the environment variable `$KUBECONFIG`. Choose the context to run `kubectl` commands from your CI/CD scripts. ### Authorize the agent to access projects in your groups @@ -104,7 +105,8 @@ To authorize the agent to access all of the GitLab projects in a group or subgro - You can authorize up to 100 groups. All the projects that belong to the group and its subgroups are now authorized to access the agent. -All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +All CI/CD jobs now include a `kubeconfig` file with contexts for every shared agent connection. +The `kubeconfig` path is available in an environment variable `$KUBECONFIG`. Choose the context to run `kubectl` commands from your CI/CD scripts. ## Update your `.gitlab-ci.yml` file to run `kubectl` commands @@ -159,10 +161,10 @@ When you deploy to an environment that has both a - The certificate-based cluster's context is called `gitlab-deploy`. This context is always selected by default. -- In GitLab 14.9 and later, agent contexts are included in the - `KUBECONFIG`. You can select them by using `kubectl config use-context path/to/agent/repository:agent-name`. +- In GitLab 14.9 and later, agent contexts are included in `$KUBECONFIG`. + You can select them by using `kubectl config use-context path/to/agent/repository:agent-name`. - In GitLab 14.8 and earlier, you can still use agent connections, but for environments that - already have a certificate-based cluster, the agent connections are not included in the `KUBECONFIG`. + already have a certificate-based cluster, the agent connections are not included in `$KUBECONFIG`. To use an agent connection when certificate-based connections are present, you can manually configure a new `kubectl` configuration context. For example: @@ -183,6 +185,17 @@ deploy: # ... rest of your job configuration ``` +### Environments with KAS that use self-signed certificates + +If you use an environment with KAS and a self-signed certificate, you must configure your Kubernetes client to trust the certificate authority (CA) that signed your certificate. + +To configure your client, do one of the following: + +- Set a CI/CD variable `SSL_CERT_FILE` with the KAS certificate in PEM format. +- Configure the Kubernetes client with `--certificate-authority=$KAS_CERTIFICATE`, where `KAS_CERTIFICATE` is a CI/CD variable with the CA certificate of KAS. +- Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner. +- Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`. + ## Restrict project and group access by using impersonation **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. @@ -340,3 +353,16 @@ If you attempt to use `kubectl` without TLS, you might get an error like: $ kubectl get pods error: You must be logged in to the server (the server has asked for the client to provide credentials) ``` + +### Unable to connect to the server: certificate signed by unknown authority + +If you use an environment with KAS and a self-signed certificate, your `kubectl` call might return this error: + +```plaintext +kubectl get pods +Unable to connect to the server: x509: certificate signed by unknown authority +``` + +The error occurs because the job does not trust the certificate authority (CA) that signed the KAS certificate. + +To resolve the issue, [configure `kubectl` to trust the CA](#environments-with-kas-that-use-self-signed-certificates). diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 1d71f6ac511..106f751555a 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md index 9a3537aacbf..98840080716 100644 --- a/doc/user/clusters/agent/gitops/flux.md +++ b/doc/user/clusters/agent/gitops/flux.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,7 +15,7 @@ You can use Flux to: To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). -Support for Flux is in [Open Beta](../../../../policy/alpha-beta-support.md#beta-features). +Support for Flux is in [Beta](../../../../policy/alpha-beta-support.md#beta). ## Bootstrap installation diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index 5f902002f83..88cc824b6b2 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -1,19 +1,21 @@ --- -stage: Configure -group: Configure -info: A tutorial using Flux with Project Access Tokens +stage: Deploy +group: Environments +info: A tutorial using Flux --- # Tutorial: Set up Flux for GitOps **(FREE)** This tutorial teaches you how to set up Flux for GitOps. You'll set up a sample project, complete a bootstrap Flux installation, and authenticate your installation with a -[project access token](../../../project/settings/project_access_tokens.md). +[project deploy token](../../../project/deploy_tokens/index.md). -You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. +You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). +It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. -To set up Flux with a project access token: +To set up Flux for GitOps: +1. [Create a personal access token](#create-a-personal-access-token) 1. [Create the Flux repository](#create-the-flux-repository) 1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) 1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) @@ -21,27 +23,31 @@ To set up Flux with a project access token: Prerequisites: -- On GitLab SaaS, you must have the Premium or Ultimate tier to use a project access token. - On self-managed instances, you can have any tier. -- Not recommended. You can authenticate with a [personal or group access token](flux.md#bootstrap-installation) in all tiers. - You must have a Kubernetes cluster running. -## Create the Flux repository +## Create a personal access token -To start, create a Git repository, install Flux, and authenticate Flux with your repo: +To authenticate with the Flux CLI, you must create a personal access token +with the `api` scope: -1. Make sure your `kubectl` is configured to access your cluster. -1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). -1. In GitLab, create a new empty project called `flux-config`. -1. In the `flux-config` project, create a [project access token](../../../project/settings/project_access_tokens.md#create-a-project-access-token) with the following settings: +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Access Tokens**. +1. Enter a name and optional expiry date for the token. +1. Select the `api` scope. +1. Select **Create personal access token**. - - From the **Select a role** dropdown list, select **Maintainer**. - - Under **Select scopes**, select the **API** and **write_repository** checkboxes. +You can also use a [project](../../../project/settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md) with the `api` scope. - Name the project token `flux-project-access-token`. +## Create the Flux repository -1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your project access token. - For example, `export GITLAB_TOKEN=<flux-project-access-token>`. +Create a Git repository, install Flux, and authenticate Flux with your repo: + +1. Make sure your `kubectl` is configured to access your cluster. +1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). You must install Flux v2 or higher. +1. In GitLab, create a new empty project called `flux-config`. +1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your personal access token. + For example, `export GITLAB_TOKEN=<personal-access-token>`. 1. Run the `bootstrap` command. The exact command depends on whether you are creating the Flux repository under a GitLab user, group, or subgroup. For more information, see the [Flux bootstrap documentation](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise). @@ -54,11 +60,13 @@ To start, create a Git repository, install Flux, and authenticate Flux with your --repository=flux-config \ --branch=main \ --path=clusters/my-cluster + --deploy-token-auth ``` This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository `flux-config`. + The command also automatically creates the project deploy token required to access the `flux-config` repository. -Great work! You now have a repository, a project access token, and a Flux bootstrap installation authenticated to your repo. Any updates to your repo are automatically synced to the cluster. +Great work! You now have a repository bootstrapped with a Flux configuration. Any updates to your repository are automatically synced to the cluster. ## Create the Kubernetes manifest repository @@ -93,7 +101,7 @@ Next, create a repository for your Kubernetes manifests: - containerPort: 80 ``` -1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the **read_repository** scope. +1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the `read_repository` scope. 1. Store your deploy token username and password somewhere safe. 1. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example: diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index b9a59d37f5d..182fd87e6f9 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -1,10 +1,10 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)** +# Using Helm charts to update a Kubernetes cluster (Experiment) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. > - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. @@ -13,11 +13,11 @@ You can deploy Helm charts to your Kubernetes cluster and keep the resources in with your charts and values. To do this, you use the pull-based GitOps features of the agent for Kubernetes. -This feature is in Alpha and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) +This feature is an Experiment and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) to track future work. Tell us about your use cases by leaving comments in the epic. NOTE: -This feature is Alpha. In future releases, to accommodate new features, the configuration format might change without notice. +This feature is an Experiment. In future releases, to accommodate new features, the configuration format might change without notice. ## GitOps workflow steps diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index 8a47dcfaf72..6e1b7da9c6c 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 0d84a617808..07149ccd8fc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -57,9 +57,9 @@ This workflow has a weaker security model and is not recommended for production GitLab supports the following Kubernetes versions. You can upgrade your Kubernetes version to a supported version at any time: +- 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) - 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported) -- 1.23 (support ends on February 22, 2023 or when 1.26 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 297210ab8ef..1bcbb42fc8e 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -138,6 +138,23 @@ By default, the Helm installation command generated by GitLab: To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml). +##### Use the agent when KAS is behind a self-signed certificate + +When [KAS](../../../../administration/clusters/kas.md) is behind a self-signed certificate, +you can set the value of `config.caCert` to the certificate. For example: + +```shell +helm update --install gitlab-agent gitlab/gitlab-agent \ + --set-file config.caCert=my-custom-ca.pem +``` + +In this example, `my-custom-ca.pem` is the path to a local file that contains +the CA certificate used by KAS. The certificate is automatically stored in a +config map and mounted in the `agentk` pod. + +If KAS is installed with the GitLab chart, and the chart is configured to provide +an [auto-generated self-signed wildcard certificate](https://docs.gitlab.com/charts/installation/tls.html#option-4-use-auto-generated-self-signed-wildcard-certificate), you can extract the CA certificate from the `RELEASE-wildcard-tls-ca` secret. + ##### Use the agent behind an HTTP proxy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351867) in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables. @@ -155,6 +172,10 @@ helm upgrade --install gitlab-agent gitlab/gitlab-agent \ ... ``` +NOTE: +DNS rebind protection is disabled when either the `HTTP_PROXY` or the `HTTPS_PROXY` environment variable is set, +and the domain DNS can't be resolved. + #### Advanced installation method GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 84cdbbcc096..d058a583b19 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 0b0e1365604..2d54f67724e 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 910092eb4e0..6f00466bc7e 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index 0721cea965a..57526394301 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index dc6898bd3d3..c6a61f58974 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index b5600096856..2c67afefd98 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f2eb0cfbc39..0ad3fdbef2e 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 9edb012ba92..4b6c8dcac4c 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index 42510a93495..fde8e455421 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- |