diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-17 14:33:21 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-17 14:33:21 +0300 |
commit | 7021455bd1ed7b125c55eb1b33c5a01f2bc55ee0 (patch) | |
tree | 5bdc2229f5198d516781f8d24eace62fc7e589e9 /doc/user/clusters | |
parent | 185b095e93520f96e9cfc31d9c3e69b498cdab7c (diff) |
Add latest changes from gitlab-org/gitlab@15-6-stable-eev15.6.0-rc42
Diffstat (limited to 'doc/user/clusters')
-rw-r--r-- | doc/user/clusters/agent/ci_cd_workflow.md | 55 | ||||
-rw-r--r-- | doc/user/clusters/agent/gitops/helm.md | 40 | ||||
-rw-r--r-- | doc/user/clusters/agent/index.md | 7 | ||||
-rw-r--r-- | doc/user/clusters/agent/install/index.md | 4 | ||||
-rw-r--r-- | doc/user/clusters/agent/troubleshooting.md | 21 | ||||
-rw-r--r-- | doc/user/clusters/management_project.md | 2 | ||||
-rw-r--r-- | doc/user/clusters/management_project_template.md | 1 |
7 files changed, 96 insertions, 34 deletions
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 7a3c09687a5..454be3c53c7 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -58,7 +58,8 @@ Authorization configuration can take one or two minutes to propagate. ### Authorize the agent to access your projects -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6. To authorize the agent to access the GitLab project where you keep Kubernetes manifests: @@ -72,7 +73,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma - id: path/to/project ``` - - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - Authorized projects must have the same root group as the agent's configuration project. - You can install additional agents into the same cluster to accommodate additional hierarchies. - You can authorize up to 100 projects. @@ -81,7 +82,8 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. ### Authorize the agent to access projects in your groups -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6. To authorize the agent to access all of the GitLab projects in a group or subgroup: @@ -95,7 +97,7 @@ To authorize the agent to access all of the GitLab projects in a group or subgro - id: path/to/group/subgroup ``` - - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - Authorized groups must have the same root group as the agent's configuration project. - You can install additional agents into the same cluster to accommodate additional hierarchies. - All of the subgroups of an authorized group also have access to the same agent (without being specified individually). - You can authorize up to 100 groups. @@ -125,6 +127,30 @@ deploy: If you are not sure what your agent's context is, open a terminal and connect to your cluster. Run `kubectl config get-contexts`. +### Environments that use Auto DevOps + +If Auto DevOps is enabled, you must define the CI/CD variable `KUBE_CONTEXT`. +Set the value of `KUBE_CONTEXT` to the context of the agent you want Auto DevOps to use: + +```yaml +deploy: + variables: + KUBE_CONTEXT: <path_to_agent_config_repository>:<agent_name> +``` + +You can assign different agents to separate Auto DevOps jobs. For instance, +Auto DevOps can use one agent for `staging` jobs, and another agent for `production` jobs. +To use multiple agents, define an [environment-scoped CI/CD variable](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) +for each agent. For example: + +1. Define two variables named `KUBE_CONTEXT`. +1. For the first variable: + 1. Set the `environment` to `staging`. + 1. Set the value to the context of your staging agent. +1. For the second variable: + 1. Set the `environment` to `production`. + 1. Set the value to the context of your production agent. + ### Environments with both certificate-based and agent-based connections When you deploy to an environment that has both a @@ -156,20 +182,6 @@ deploy: # ... rest of your job configuration ``` -### Using the agent with Auto DevOps - -If Auto DevOps is enabled, you must define the `KUBE_CONTEXT` CI/CD variable. Set the value of `KUBE_CONTEXT` to the context of the agent you want to use in your Auto DevOps pipeline jobs (`<PATH_TO_AGENT_CONFIG_REPOSITORY>:<AGENT_NAME>`). - -You can also use different agents for different Auto DevOps jobs. For instance, you can use one agent for `staging` jobs and a different agent for `production` jobs. To use multiple agents, define a unique CI/CD variable for each agent. - -For example: - -1. Add two [environment-scoped CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) and name both `KUBE_CONTEXT`. -1. Set the `environment` of the first variable to `staging`. Set the value of the variable to `<PATH_TO_AGENT_CONFIGURATION_PROJECT>:<STAGING_AGENT_NAME>`. -1. Set the `environment` of the second variable to `production`. Set the value of the variable to `<PATH_TO_AGENT_CONFIGURATION_PROJECT>:<PRODUCTION_AGENT_NAME>`. - -When the `staging` job runs, it will connect to the cluster via the agent named `<STAGING_AGENT_NAME>`, and when the `production` job runs it will connect to the cluster via the agent named `<PRODUCTION_AGENT_NAME>`. - ## Restrict project and group access by using impersonation **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. @@ -281,13 +293,6 @@ See the [official Kubernetes documentation for details](https://kubernetes.io/do ## Troubleshooting -### `kubectl` commands not supported - -The commands `kubectl exec`, `kubectl cp`, `kubectl attach`, `kubectl run --attach=true` and `kubectl port-forward` are not supported. -Anything that uses these API endpoints does not work, because they use the deprecated -SPDY protocol. -[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/346248) to add support for these commands. - ### Grant write permissions to `~/.kube/cache` Tools like `kubectl`, Helm, `kpt`, and `kustomize` cache information about diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index af9f80618b5..0ec87376636 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -54,16 +54,50 @@ gitops: path: dir-in-project/with/charts namespace: my-ns max_history: 1 + values: + - inline: + someKey: example value ``` | Keyword | Description | |--|--| | `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. | | `release_name` | Required. Name of the release to use when applying the chart. | -| `id` | Required. ID of the project where Helm chart is committed. No authentication mechanisms are currently supported. | -| `path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. This is the directory with the `Chart.yaml` file. | +| `values` | Optional. [Custom values](#custom-values) for the release. An array of objects. Only supports `inline` values. | | `namespace` | Optional. Namespace to use when applying the chart. Defaults to `default`. | | `max_history` | Optional. Maximum number of release [revisions to store in the cluster](https://helm.sh/docs/helm/helm_history/). | +| `source` | Required. From where the chart should get installed. Only supports project sources. | +| `source.project.id` | Required. ID of the project where Helm chart is committed. Authentication is not supported. | +| `source.project.path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. Should be the directory with the `Chart.yaml` file. | + +## Custom values + +> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/766) in GitLab 15.6. Requires both GitLab and the installed agent to be version 15.6 or later. + +To customize the values for a release, set the `values` key. It must be +an array of objects. Each object must have exactly one top-level key that describes +where the values come from. The supported top-level keys are: + +- `inline`: Specify the values inline in YAML format, similar to a Helm values + file. + +When installing a chart with custom values: + +- Custom values get merged on top of the chart's default `values.yaml` file. +- Values from subsequent entries in the `values` array overwrite values from + previous entries. + +Example: + +```yaml +gitops: + charts: + - release_name: some-release + values: + - inline: + someKey: example value + # ... +``` ## Automatic drift remediation @@ -98,7 +132,7 @@ The following are known issues: [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). - Values for the chart must be in a `values.yaml` file. This file must be with the chart, in the same project and path. -- Because of drift detection and remediation, release history, stored in the cluster, is not useful. +- Because of drift detection and remediation, the release history stored in the cluster is not useful. A new release is created every five minutes and the oldest release is discarded. Eventually history consists only of the same information. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372023) for details. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 7fdf0bb2bf0..8f4855a7f93 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -69,14 +69,15 @@ 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.24 (support ends on September 22, 2023 or when 1.27 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) -- 1.22 (support ends on October 22, 2022) -- 1.21 (support ends on August 22, 2022) 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. +When installing the agent, use a Helm version compatible with your Kubernetes version. Other versions of Helm might not work. For a list of compatible versions, see the [Helm version support policy](https://helm.sh/docs/topics/version_skew/). + Support for deprecated APIs can be removed from the GitLab codebase when we drop support for the Kubernetes version that only supports the deprecated API. Some GitLab features might work on versions not listed here. [This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for Kubernetes versions. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 19628419784..2030052e3b0 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -45,6 +45,8 @@ For configuration settings, the agent uses a YAML file in the GitLab project. Yo - You use [a GitOps workflow](../gitops.md#gitops-workflow-steps). - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. +Otherwise it is optional. + To create an agent configuration file: 1. Choose a name for your agent. The agent name follows the @@ -90,7 +92,7 @@ You must register an agent before you can install the agent in your cluster. To - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list. 1. Select **Register an agent**. 1. GitLab generates an access token for the agent. You need this token to install the agent - in your cluster and to [update the agent](#update-the-agent-version) to another version. + in your cluster. WARNING: Securely store the agent access token. A bad actor can use this token to access source code in the agent's configuration project, access source code in any public project on the GitLab instance, or even, under very specific conditions, obtain a Kubernetes manifest. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 0c26c533cc3..6b5f58f8f76 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -208,3 +208,24 @@ kubectl delete jobs -l app.kubernetes.io/managed-by=starboard -n gitlab-agent ``` [We're working on making the cleanup of these jobs more robust.](https://gitlab.com/gitlab-org/gitlab/-/issues/362016) + +## Inventory policy prevented actuation (strategy: Apply, status: Empty, policy: MustMatch) + +```json +{ + "error":"inventory policy prevented actuation (strategy: Apply, status: Empty, policy: MustMatch)", + "group":"networking.k8s.io", + "kind":"Deployment", + "name":"resource-name", + "namespace":"namespace", + "status":"Skipped", + "timestamp":"2022-10-29T15:34:21Z", + "type":"apply" +} +``` + +This error occurs when the GitLab agent tries to update an object and the object doesn't have the required annotations. To fix this error, you can: + +- Add the required annotations manually. +- Delete the object and let the agent recreate it. +- Change your [`inventory_policy`](../../infrastructure/clusters/deploy/inventory_object.md#inventory_policy-options) setting. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index df338e8fcee..18317ae09ed 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -63,7 +63,7 @@ To associate a cluster management project with your cluster: page. - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Main menu > Admin > Kubernetes**. 1. Expand **Advanced settings**. -1. From the **Cluster management project** dropdown, select the cluster management project +1. From the **Cluster management project** dropdown list, select the cluster management project you created in the previous step. ### Configuring your pipeline diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index bdd11f11f9c..cbe577b9b74 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -103,7 +103,6 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [GitLab Runner](../infrastructure/clusters/manage/management_project_applications/runner.md) - [Ingress](../infrastructure/clusters/manage/management_project_applications/ingress.md) - [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md) -- [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) Each application has an `applications/{app}/values.yaml` file. |