diff options
Diffstat (limited to 'doc/user/clusters/agent')
| -rw-r--r-- | doc/user/clusters/agent/index.md | 65 | ||||
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 96 |
2 files changed, 130 insertions, 31 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 74c679d9bb9..5963485aebc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- stage: Configure 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/#designated-technical-writers +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 --- # GitLab Kubernetes Agent **(PREMIUM ONLY)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) @@ -56,6 +56,12 @@ There are several components that work in concert for the Agent to accomplish Gi These repositories might be the same GitLab project or separate projects. +NOTE: +GitLab recommends you use the same GitLab project for the agent configuration +and manifest repositories. Our backlog contains issues for adding support for +[private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and +[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). + For more details, please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. ## Get started with GitOps and the GitLab Agent @@ -82,8 +88,8 @@ Upgrade your agent installations together with GitLab upgrades. To decide which 1. Open the [GITLAB_KAS_VERSION](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) -The available `agentk` versions can be found in -[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). +The available `agentk` and `kas` versions can be found in +[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). ### Install the Kubernetes Agent Server @@ -93,7 +99,7 @@ chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have GitLab installed, please refer to our [installation documentation](https://docs.gitlab.com/ee/install/README.html). -NOTE: **Note:** +NOTE: GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). #### Install with Omnibus @@ -161,23 +167,9 @@ gitops: ``` GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also -supports manifest projects containing multiple directories (or subdirectories) -of YAML files. To use multiple YAML files, specify a `paths` attribute: - -```yaml -gitops: - manifest_projects: - - id: "path-to/your-manifest-project-number1" - paths: - # Read all .yaml files from team1/app1 directory. - # See https://github.com/bmatcuk/doublestar#about and - # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. - - glob: '/team1/app1/*.yaml' - # Read all .yaml files from team2/apps and all subdirectories - - glob: '/team2/apps/**/*.yaml' - # If 'paths' is not specified or is an empty list, the configuration below is used - - glob: '/**/*.{yaml,yml,json}' -``` +supports manifest projects containing +multiple directories (or subdirectories) of YAML files. For more information see our +documentation on the [Kubernetes Agent configuration respository](repository.md). ### Create an Agent record in GitLab @@ -223,7 +215,7 @@ the Agent in subsequent steps. You can create an Agent record either: } ``` - NOTE: **Note:** + NOTE: GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the @@ -257,11 +249,14 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. Select the option appropriate for your cluster configuration and GitLab architecture: - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install `gitlab-kas` sub-chart or enable `kas` for Omnibus GitLab. - In this case, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as + after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. + When using the sub-chart, you must set `wss://kas.host.tld:443` as + `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. + When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - Specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`) + - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` @@ -270,6 +265,10 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. + Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + to learn more about it. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your secret name in the `secretName:` section. @@ -317,7 +316,8 @@ spec: args: - --token-file=/config/token - --kas-address - - wss://gitlab.host.tld:443/-/kubernetes-agent + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -392,9 +392,12 @@ subjects: In a previous step, you configured a `config.yaml` to point to the GitLab projects the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a -templating engine or other means. Only public projects are supported as -manifest projects. Support for private projects is planned in the issue -[Agent authorization for private manifest projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +templating engine or other means. + +The agent is authorized to download manifests for the configuration +project, and public projects. Support for other private projects is +planned in the issue [Agent authorization for private manifest +projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). Each time you commit and push a change to this file, the Agent logs the change: @@ -548,7 +551,7 @@ issue is in progress, directly edit the deployment with the `kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use `grpc://gitlab-kas.<YOUR-NAMESPACE>:5005`. -#### Agent logs - Decompressor is not installed for grpc-encoding +### Agent logs - Decompressor is not installed for grpc-encoding ```plaintext {"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md new file mode 100644 index 00000000000..b71bbc29ef9 --- /dev/null +++ b/doc/user/clusters/agent/repository.md @@ -0,0 +1,96 @@ +--- +stage: Configure +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/#designated-technical-writers +--- + +# Kubernetes Agent configuration repository **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The [GitLab Kubernetes Agent integration](index.md) supports hosting your configuration for +multiple GitLab Kubernetes Agents in a single repository. These agents can be running +in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster. + +The Agent bootstraps with the GitLab installation URL and an authentication token, +and you provide the rest of the configuration in your repository, following +Infrastructure as Code (IaaC) best practices. + +A minimal repository layout looks like this, with `my_agent_1` as the name +of your Agent: + +```plaintext +|- .gitlab + |- agents + |- my_agent_1 + |- config.yaml +``` + +## Synchronize manifest projects + +Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` +section. Each `id` in the `manifest_projects` section is the path to a Git repository +with Kubernetes resource definitions in YAML or JSON format. The Agent monitors +each project you declare, and when the project changes, GitLab deploys the changes +using the Agent. + +To use multiple YAML files, specify a `paths` attribute in the `gitops` section. + +By default, the Agent monitors all +[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). +You can exclude some types of resources from monitoring. This enables you to reduce +the permissions needed by the GitOps feature, through `resource_exclusions`. + +To enable a specific named resource, first use `resource_inclusions` to enable desired resources. +The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` +which follow excludes all other `api_groups` and `kinds`: + +```yaml +gitops: + # Manifest projects are watched by the agent. Whenever a project changes, + # GitLab deploys the changes using the agent. + manifest_projects: + # No authentication mechanisms are currently supported. + # The `id` is a path to a Git repository with Kubernetes resource definitions + # in YAML or JSON format. + - id: gitlab-org/cluster-integration/gitlab-agent + # Holds the only API groups and kinds of resources that gitops will monitor. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning + resource_inclusions: + - api_groups: + - apps + kinds: + - '*' + - api_groups: + - '' + kinds: + - 'ConfigMap' + # Holds the API groups and kinds of resources to exclude from gitops watch. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + resource_exclusions: + - api_groups: + - '*' + kinds: + - '*' + # Namespace to use if not set explicitly in object manifest. + default_namespace: my-ns + # Paths inside of the repository to scan for manifest files. + # Directories with names starting with a dot are ignored. + paths: + # Read all .yaml files from team1/app1 directory. + # See https://github.com/bmatcuk/doublestar#about and + # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used + - glob: '/**/*.{yaml,yml,json}' +``` |