diff options
Diffstat (limited to 'doc/user/clusters/agent')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_workflow.md | 54 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops.md | 8 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/example_repository_structure.md | 78 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/flux.md | 36 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/flux_tutorial.md | 192 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/helm.md | 10 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/secrets_management.md | 10 | ||||
| -rw-r--r-- | doc/user/clusters/agent/index.md | 26 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 25 | ||||
| -rw-r--r-- | doc/user/clusters/agent/troubleshooting.md | 117 | ||||
| -rw-r--r-- | doc/user/clusters/agent/work_with_agent.md | 4 |
11 files changed, 459 insertions, 101 deletions
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 982411d35f9..7a3f09f50ca 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,28 @@ 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). + +### Validation errors + +If you use `kubectl` versions v1.27.0 or v.1.27.1, you might get the following error: + +```plaintext +error: error validating "file.yml": error validating data: the server responded with the status code 426 but did not return more information; if you choose to ignore these errors, turn validation off with --validate=false +``` + +This issue is caused by [a bug](https://github.com/kubernetes/kubernetes/issues/117463) with `kubectl` and other tools that use the shared Kubernetes libraries. + +To resolve the issue, use another version of `kubectl`. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 787b0062017..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 --- @@ -12,6 +12,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7. > - 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. +NOTE: +From GitLab 15.10, you should use [Flux](gitops/flux.md) for GitOps. For more information, see +[this announcement blog post](https://about.gitlab.com/blog/2023/02/08/why-did-we-choose-to-integrate-fluxcd-with-gitlab/). + With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md new file mode 100644 index 00000000000..93c05e40bfd --- /dev/null +++ b/doc/user/clusters/agent/gitops/example_repository_structure.md @@ -0,0 +1,78 @@ +--- +stage: Deploy +group: Environments +info: An example of how to structure a repository for GitOps deployments +--- + +# Example GitOps repository structure **(FREE)** + +This page describes an example structure for a project that builds and deploys an application +to a Kubernetes cluster with [GitOps](https://about.gitlab.com/topics/gitops) and the +[GitLab agent for Kubernetes](../../agent/gitops.md). + +You can find an example project that uses this structure +[in this GitLab repository](https://gitlab.com/tigerwnz/minimal-gitops-app). You can use the example project +as a starting point to create your own deployment project. + +## Deployment workflow + +The default branch is the single source of truth for your application and the +Kubernetes manifests that deploy it. To be reflected in a Kubernetes cluster, +a code or configuration change must exist in the default branch. + +A GitLab agent for Kubernetes is installed in every Kubernetes cluster. The agent +is configured to sync manifests from a corresponding branch in the repository. +These branches represent the state of each cluster, and contain only commits that +exist in the default branch. + +Changes are deployed by merging the default branch into the branch of a cluster. +The agent that watches the branch picks up the change and syncs it to the cluster. + +For the actual deployment, the example project uses the GitLab agent for Kubernetes, +but you can also use other GitOps tools. + +### Review apps + +Ephemeral environments such as [review apps](../../../../ci/review_apps/index.md) +are deployed differently. Their configuration does not exist on the default branch, +and the changes are not meant to be deployed to a permanent environment. Review app +manifests are generated and deployed in a merge request feature branch, which is removed +when the MR is merged. + +## Example deployment + +The example project deploys to two permanent environments, staging and production, +which each have a dedicated Kubernetes cluster. A third cluster is used for ephemeral +review apps. + +Each cluster has a corresponding branch that represents the current state of the cluster: +`_gitlab/agents/staging`, `_gitlab/agents/production` and `_gitlab/agents/review`. Each branch is +[protected](../../../../user/project/protected_branches.md) and +a [project access token](../../../../user/project/settings/project_access_tokens.md) +is created for each branch with a configuration that allows only the corresponding token to push to the branch. +This ensures that environment branches are updated only through the configured process. + +Deployment branches are updated by CI/CD jobs. The access token that allows pushing to each +branch is configured as a [CI/CD variable](../../../../ci/variables/index.md). These variables +are protected, and only available to pipelines running on a protected branch. +The CI/CD job merges the default branch `main` into the deployment branch, and pushes +the deployment branch back to the repository using the provided token. To preserve the +commit history between both branches, the CI/CD job uses a fast-forward merge. + +Each cluster has an agent for Kubernetes, and each agent is configured to +[sync manifests from the branch corresponding to its cluster](../gitops.md#gitops-configuration-reference). +In your own project, you can different GitOps tool like Flux, or use the same configuration to deploy +to virtual machines with GitLab CI/CD. + +### Application changes + +The example project follows this process to deploy an application change: + +1. A new feature branch is created with the desired changes. The pipeline builds an image, + runs the test suite, and deploy the changes to a review app in the `review` cluster. +1. The feature branch is merged to `main` and the review app is removed. +1. Manifests are updated on `main` (either directly or via merge request) to point to an updated + version of the deployed image. The pipeline automatically merges `main` into the `_gitlab/agents/staging` + branch, which updates the `staging` cluster. +1. The `production` job is triggered manually, and merges `main` into the `_gitlab/agents/production` branch, + deploying to the `production` cluster. diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md new file mode 100644 index 00000000000..98840080716 --- /dev/null +++ b/doc/user/clusters/agent/gitops/flux.md @@ -0,0 +1,36 @@ +--- +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 +--- + +# Flux (Beta) **(FREE)** + +Flux is a GitOps tool that helps you manage your Kubernetes clusters. +You can use Flux to: + +- Keep your clusters in sync with your Git repositories. +- Reconcile code changes with your deployments. +- Manage your Flux installation itself with a bootstrap. + +To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). + +Support for Flux is in [Beta](../../../../policy/alpha-beta-support.md#beta). + +## Bootstrap installation + +Use the Flux command [`bootstrap gitlab`](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise) +to configure a Kubernetes cluster to manage itself from a Git repository. + +You must authenticate your installation with either: + +- Recommended. [A project access token](../../../project/settings/project_access_tokens.md). +- A [group access token](../../../group/settings/group_access_tokens.md). +- A [personal access token](../../../profile/personal_access_tokens.md). + +Some Flux features like [automated image updates](https://fluxcd.io/flux/guides/image-update/) require +write access to the source repositories. + +## GitOps repository structure + +You should organize your repositories to meet the needs of your team. For detailed recommendations, see the Flux [repository structure documentation](https://fluxcd.io/flux/guides/repository-structure/). diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md new file mode 100644 index 00000000000..bdb772ac14e --- /dev/null +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -0,0 +1,192 @@ +--- +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 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. + +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) +1. [Verify your configuration](#verify-your-configuration) + +Prerequisites: + +- You must have a Kubernetes cluster running. + +## Create a personal access token + +To authenticate with the Flux CLI, you must create a personal access token +with the `api` scope: + +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**. + +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. + +## Create the Flux repository + +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). + + In this tutorial, you're working with a public project in a subgroup. The bootstrap command looks like this: + + ```shell + flux bootstrap gitlab \ + --owner=gitlab-org/configure/examples/flux \ + --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 bootstrapped with a Flux configuration. Any updates to your repository are automatically synced to the cluster. + +## Create the Kubernetes manifest repository + +Next, create a repository for your Kubernetes manifests: + +1. In GitLab, create a new repository called `web-app-manifests`. +1. Add a file to `web-app-manifests` named `nginx-deployment.yaml` with the following contents: + + ```yaml + apiVersion: apps/v1 + + kind: Deployment + + metadata: + name: nginx-deployment + labels: + app: nginx + spec: + replicas: 3 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - 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. 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: + + ```shell + flux create secret git flux-deploy-authentication \ + --url=https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests \ + --namespace=default \ + --username=<token-user-name> \ + --password=<token-password> + ``` + +1. To check if your secret was generated successfully, run: + + ```shell + kubectl -n default get secrets flux-deploy-authentication -o yaml + ``` + + Under `data`, you should see base64-encoded values associated with your token username and password. + +Congratulations! You now have a manifest repository, a deploy token, and a secret generated directly on your cluster. + +## Configure Flux to sync your manifests + +Next, tell `flux-config` to sync with the `web-app-manifests` repository. + +To do so, create a [`GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) resource: + +1. Clone the `flux-config` repo to your machine. +1. In your local clone of `flux-config`, add the `GitRepository` file `clusters/my-cluster/web-app-manifests-source.yaml`: + + ```yaml + --- + apiVersion: source.toolkit.fluxcd.io/v1beta2 + kind: GitRepository + metadata: + name: web-app-manifests + namespace: default + spec: + interval: 1m0s + ref: + branch: main + secretRef: + name: flux-deploy-authentication + url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests + ``` + + This file uses `secretRef` to refer back to the deploy token secret you created in the last step. + +1. In your local clone of `flux-config`, add the `GitRepository` file `clusters/my-cluster/web-app-manifests-kustomization.yaml`: + + ```yaml + --- + apiVersion: kustomize.toolkit.fluxcd.io/v1beta2 + kind: Kustomization + metadata: + name: nginx-source-kustomization + namespace: default + spec: + interval: 1m0s + path: ./ + prune: true + sourceRef: + kind: GitRepository + name: web-app-manifests + namespace: default + targetNamespace: default + ``` + + This file adds a [`Kustomization`](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests from + `web-app-manifests` with `kustomize`. + +1. Commit the new files and push. + +## Verify your configuration + +You should see a newly created `nginx-deployment` pod in your cluster. + +To check whether the `nginx-deployment` pod is running in the default namespace, run the following: + +```shell +kubectl -n default get pods -n default +``` + +If you want to see the deployment sync again, try updating the number of replicas in the +`nginx-deployment.yaml` file and push to your `main` branch. If all is working well, it +should sync to the cluster. + +Excellent work! You've successfully set up a complete Flux project. 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 dc1cbe3009d..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 --- @@ -50,9 +50,9 @@ To deploy containers from the GitLab Container Registry, you must configure the 1. Generate a GitLab token with at least `read-registry` rights. The token can be either a Personal or a Project Access Token. 1. Create a Kubernetes secret manifest YAML file. Update the values as needed: - ```shell - kubectl create secret docker-registry gitlab-credentials --docker-server=registry.gitlab.example.com --docker-username=<gitlab-username> --docker-password=<gitlab-token> --docker-email=<gitlab-user-email> -n <namespace> --dry-run=client -o yaml > gitlab-credentials.yaml - ``` + ```shell + kubectl create secret docker-registry gitlab-credentials --docker-server=registry.gitlab.example.com --docker-username=<gitlab-username> --docker-password=<gitlab-token> --docker-email=<gitlab-user-email> -n <namespace> --dry-run=client -o yaml > gitlab-credentials.yaml + ``` 1. Encrypt the secret into a `SealedSecret` manifest: diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 8f4855a7f93..ccb3a346903 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 --- @@ -12,6 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6. +> - Flux [recommended](https://gitlab.com/gitlab-org/gitlab/-/issues/357947#note_1253489000) as GitOps solution in GitLab 15.10. You can connect your Kubernetes cluster with GitLab to deploy, manage, and monitor your cloud-native solutions. @@ -33,20 +34,7 @@ You can choose from two primary workflows. The GitOps workflow is recommended. ### GitOps workflow -In a [**GitOps** workflow](gitops.md): - -- You keep your Kubernetes manifests in GitLab. -- You install a GitLab agent in your cluster. -- Any time you update your manifests, the agent updates the cluster. -- The cluster automatically cleans up unexpected changes. It uses - [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/) - to fix any configuration inconsistencies that third parties introduce. - -This workflow is fully driven with Git and is considered **pull-based**, -because the cluster is pulling updates from your GitLab repository. - -GitLab recommends this workflow. We are actively investing in this workflow -so we can provide a first-class experience. +You should use Flux for GitOps. To get started, see the GitLab [Flux documentation](../../../user/clusters/agent/gitops/flux.md). ### GitLab CI/CD workflow @@ -64,14 +52,14 @@ Use this workflow: This workflow has a weaker security model and is not recommended for production deployments. -## Supported cluster versions +## GitLab agent for Kubernetes supported cluster versions -GitLab supports the following Kubernetes versions. You can upgrade your +The agent for Kubernetes 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 f5f235d2758..531dac20fb6 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 --- @@ -107,71 +107,72 @@ This error occurs when your GitLab instance is using a certificate signed by an certificate authority that is unknown to the agent. To fix this issue, you can present the CA certificate file to the agent -by using a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it -is picked up automatically. +by [customizing the Helm installation](install/index.md#customize-the-helm-installation). +Add `--set config.caCert="$(cat ~/path/to/ca.crt)"` to the `helm install` command. Make sure to replace `~/path/to/ca.crt` +with the path to your internal CA's certificate file. The file should be a valid PEM or DER-encoded certificate. -For example, if your internal CA certificate is `myCA.pem`: +When you deploy `agentk` with a set `config.caCert` value, the certificate is added to `configmap` and the certificate file is mounted in `/etc/ssl/certs`. -```plaintext -kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem +```yaml +$ kubectl get configmap -lapp=gitlab-agent -o yaml +apiVersion: v1 +items: +- apiVersion: v1 + data: + ca.crt: |- + -----BEGIN CERTIFICATE----- + MIIFmzCCA4OgAwIBAgIUE+FvXfDpJ869UgJitjRX7HHT84cwDQYJKoZIhvcNAQEL + ...truncated certificate... + GHZCTQkbQyUwBWJOUyOxW1lro4hWqtP4xLj8Dpq1jfopH72h0qTGkX0XhFGiSaM= + -----END CERTIFICATE----- + kind: ConfigMap + metadata: + annotations: + meta.helm.sh/release-name: self-signed + meta.helm.sh/release-namespace: gitlab-agent-self-signed + creationTimestamp: "2023-03-07T20:12:26Z" + labels: + app: gitlab-agent + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: gitlab-agent + app.kubernetes.io/version: v15.9.0 + helm.sh/chart: gitlab-agent-1.11.0 + name: self-signed-gitlab-agent + resourceVersion: "263184207" +kind: List ``` -Then in `resources.yml`: +You might see a similar error in the [agent server (KAS) logs](../../../administration/logs/index.md#gitlab-agent-server) of your GitLab application server: -```yaml - spec: - serviceAccountName: gitlab-agent - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /etc/ssl/certs/myCA.pem - subPath: myCA.pem - volumes: - - name: token-volume - secret: - secretName: gitlab-agent-token - - name: ca-pemstore-volume - configMap: - name: ca-pemstore - items: - - key: myCA.pem - path: myCA.pem +```json +{"level":"error","time":"2023-03-07T20:19:48.151Z","msg":"AgentInfo()","grpc_service":"gitlab.agent.agent_configuration.rpc.AgentConfiguration","grpc_method":"GetConfiguration","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": x509: certificate signed by unknown authority"} ``` -Alternatively, you can mount the certificate file at a different location and specify it for the -`--ca-cert-file` agent parameter: +To fix it, [install your internal CA's public certificate](https://docs.gitlab.com/omnibus/settings/ssl/#install-custom-public-certificates) in the `/etc/gitlab/trusted-certs` directory. -```yaml - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --ca-cert-file=/tmp/myCA.pem - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /tmp/myCA.pem - subPath: myCA.pem +Alternatively, you can configure the agent server (KAS) to read the certificate from a custom directory. +Add the following configuration to `/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_kas['env'] = { + 'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/" + } ``` +To apply the changes: + +1. Reconfigure GitLab. + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Restart `gitlab-kas`. + + ```shell + gitlab-ctl restart gitlab-kas + ``` + ## Project not found ```json @@ -238,4 +239,4 @@ When you install the agent, you might encounter an error that states: Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): unclosed action ``` -This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-cluster-versions). +This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#gitlab-agent-for-kubernetes-supported-cluster-versions). 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 --- |