diff options
Diffstat (limited to 'doc/user/clusters/agent/repository.md')
-rw-r--r-- | doc/user/clusters/agent/repository.md | 96 |
1 files changed, 96 insertions, 0 deletions
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}' +``` |