diff options
Diffstat (limited to 'doc/user/clusters/agent')
-rw-r--r-- | doc/user/clusters/agent/ci_cd_tunnel.md | 46 | ||||
-rw-r--r-- | doc/user/clusters/agent/index.md | 48 | ||||
-rw-r--r-- | doc/user/clusters/agent/repository.md | 35 |
3 files changed, 82 insertions, 47 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 09123fdd472..1ea5168f30c 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -4,40 +4,52 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI/CD Tunnel +# CI/CD Tunnel **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. -> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. Only CI/CD jobs set in the configuration project can access one of the configured agents. -Prerequisites: +## Prerequisites - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server). - A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`). - An [Agent record](index.md#create-an-agent-record-in-gitlab). -- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster). +- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster). -If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected. +## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD +If your project has access to one or more Agent records available, its CI/CD +jobs provide a `KUBECONFIG` variable compatible with `kubectl`. + +Also, each Agent has a separate context (`kubecontext`). By default, +there isn't any context selected. Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. +To get the list of available contexts, run `kubectl config get-contexts`. + +## Example for a `kubectl` command using the CI/CD Tunnel -To access your cluster from a CI/CD job through the tunnel: +The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. +You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, +`kpt`, and so on. To do so: -1. In your `.gitlab-ci.yml` select the context for the agent you wish to use: +1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. +1. Run Kubernetes commands. - ```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods - ``` +For example: -1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created. +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config use-context path/to/agent-configuration-project:your-agent-name + - kubectl get pods +``` diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c59d2a1f61c..d2dc57c0849 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -20,7 +20,7 @@ tasks in a secure and cloud-native way. It enables: - Pull-based GitOps deployments. - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. - Real-time access to API endpoints in a cluster. -- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy). +- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy). - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) @@ -77,6 +77,8 @@ The setup process involves a few steps to enable GitOps deployments: 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). 1. [Create manifest files](#create-manifest-files). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. + ### Upgrades and version compatibility As the GitLab Kubernetes Agent is a new product, we are constantly adding new features @@ -104,7 +106,8 @@ To use the KAS: ### Define a configuration repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. To configure an Agent, you need: @@ -123,6 +126,7 @@ In your repository, add the Agent configuration file under: Your `config.yaml` file specifies all configurations of the Agent, such as: - The manifest projects to synchronize. +- The groups that can access this Agent via the [CI/CD Tunnel](ci_cd_tunnel.md). - The address of the `hubble-relay` for the Network Security policy integrations. As an example, a minimal Agent configuration that sets up only the manifest @@ -174,17 +178,14 @@ To perform a one-liner installation, run the command below. Make sure to replace - `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). - `gitlab-kubernetes-agent` with the namespace you defined in the previous step. - `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. +- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - ``` -Set `--agent-version` to the latest released patch version matching your -GitLab installation's major and minor versions. For example, if you have -GitLab v13.9.0, set `--agent-version=v13.9.1`. - WARNING: -Version `stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for +`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for testing purposes but for production please make sure to specify a matching version explicitly. To find out the various options the above Docker container supports, run: @@ -287,7 +288,7 @@ spec: containers: - name: agent # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z args: - --token-file=/config/token - --kas-address @@ -383,29 +384,16 @@ Each time you push a change to a monitored manifest repository, the Agent logs t #### Example manifest file -This file creates an NGINX deployment. +This file creates a minimal `ConfigMap`: ```yaml -apiVersion: apps/v1 -kind: Deployment +apiVersion: v1 +kind: ConfigMap metadata: - name: nginx-deployment + name: demo-map namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -spec: - selector: - matchLabels: - app: nginx - replicas: 2 - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 +data: + key: value ``` ## Example projects @@ -433,8 +421,8 @@ There are several components that work in concert for the Agent to generate the - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an existing installation. - One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration. + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - Add the required labels and annotations to existing network policies. - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index a3a3e4c29b0..ea57ded3320 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +> - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -147,6 +148,40 @@ gitops: - glob: '/**/*.yaml' ``` +## Authorize groups to use an Agent + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel +to grant the Agent access to one or more groups. This way, all the projects that belong +to the authorized groups can access the same Agent. This enables you to save resources and +have a scalable setup. + +When you authorize a group, the agent's Kubernetes context is automatically injected +into every project of the authorized group, and users can select the connection as +described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md). +To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md), +use the `ci_access` attribute in your `config.yaml` configuration file. + +An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most +100 groups can be authorized per Agent. + +To authorize a group: + +1. Edit your `.config.yaml` file under the `.gitlab/agents/<agent name>` directory. +1. Add the `ci_access` attribute. +1. Add the `groups` attribute into `ci_access`. +1. Add the group `id` into `groups`, identifying the authorized group through its path. + +For example: + +```yaml +ci_access: + # This agent is accessible from CI jobs in projects in these groups + groups: + - id: group/subgroup +``` + ## Surface network security alerts from cluster to GitLab The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). |