diff options
Diffstat (limited to 'doc/user/clusters/agent/index.md')
| -rw-r--r-- | doc/user/clusters/agent/index.md | 226 |
1 files changed, 130 insertions, 96 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 7b745577cc4..4065ee3337b 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -6,18 +6,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Kubernetes Agent **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [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). -## Goals +CAUTION: **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) is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud native way. +The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) +is an active in-cluster component for solving GitLab and Kubernetes integration +tasks in a secure and cloud-native way. It enables: -Features: +- Integrating GitLab with a Kubernetes cluster behind a firewall or NAT + (network address translation). +- Pull-based GitOps deployments by leveraging the + [GitOps Engine](https://github.com/argoproj/gitops-engine). +- Real-time access to API endpoints within a cluster. -1. Makes it possible to integrate GitLab with a Kubernetes cluster behind a firewall or NAT -1. Enables pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine) -1. Allows for real-time access to API endpoints within a cluster. -1. Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). +Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). ## Architecture @@ -39,37 +44,45 @@ sequenceDiagram end ``` -Please refer to our [full architecture documentation in the Agent project](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). +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. -## Getting started with GitOps using the GitLab Agent and the GitLab Cloud Native Helm chart +## Get started with GitOps and the GitLab Agent There are several components that work in concert for the Agent to accomplish GitOps deployments: -1. A Kubernetes cluster that is properly configured -1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with. -1. A manifest repository that contains a `manifest.yaml`. This `manifest.yaml` (which can be autogenerated) is tracked by the Agent and any changes to the file are automatically applied to the cluster. +- A properly-configured Kubernetes cluster. +- A configuration repository that contains a `config.yaml` file, which tells the + Agent which repositories to synchronize with. +- A manifest repository that contains a `manifest.yaml`, which is tracked by the + Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. -The setup process involves a few steps that, once completed, will enable GitOps deployments to work +The setup process involves a few steps to enable GitOps deployments: -1. Installing the Agent server via GitLab Helm chart -1. Defining a configuration directory -1. Creating an Agent record in GitLab -1. Generating and copying a Secret token used to connect to the Agent -1. Installing the Agent into the cluster -1. Creating a `manifest.yaml` +1. Installing the Agent server via GitLab Helm chart. +1. Defining a configuration directory. +1. Creating an Agent record in GitLab. +1. Generating and copying a Secret token used to connect to the Agent. +1. Installing the Agent into the cluster. +1. Creating a `manifest.yaml`. -### Installing the Agent server via Helm +### Install the Agent server -Currently the GitLab Kubernetes Agent can only be deployed via our [Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). +The GitLab Kubernetes Agent can only be deployed through our +[Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already +have GitLab installed via Helm, please refer to our +[installation documentation](https://docs.gitlab.com/charts/installation/). -NOTE: We are working quickly to [include the Agent in Official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060). +NOTE: **Note:** +GitLab plans to include the Agent in the [official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060) and on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). -If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/) - -When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify): +When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example. +(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true` +for the Agent to be properly installed and configured: ```shell -helm upgrade --force --install gitlab . \ +helm repo update +helm upgrade --force --install gitlab gitlab/gitlab \ --timeout 600 \ --set global.hosts.domain=<YOUR_DOMAIN> \ --set global.hosts.externalIP=<YOUR_IP> \ @@ -78,15 +91,14 @@ helm upgrade --force --install gitlab . \ --set global.kas.enabled=true ``` -`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured. - -### Defining a configuration repository +### Define a configuration repository -Next you will need a GitLab repository that will contain your Agent configuration. +Next, you need a GitLab repository to contain your Agent configuration. The minimal +repository layout looks like this: -The minimal repository layout looks like this: - -`.gitlab/agents/<agent-name>/config.yaml` +```plaintext +.gitlab/agents/<agent-name>/config.yaml +``` The `config.yaml` file contents should look like this: @@ -96,31 +108,24 @@ gitops: - id: "path-to/your-awesome-project" ``` -### Creating an Agent record in GitLab - -Next you will need to create an GitLab Rails Agent record so that your GitLab project so that the Agent itself can associate with a GitLab project. This process will also yield a Secret that you will use to configure the Agent in subsequent steps. +### Create an Agent record in GitLab -There are two ways to accomplish this: +Next, create an GitLab Rails Agent record so the Agent can associate itself with +a GitLab project. Creating this record also creates a Secret needed to configure +the Agent in subsequent steps. You can create an Agent record either: -1. Via the Rails console -1. Via GraphQL +- Through the Rails console, by running `rails c`: -To do this you could either run `rails c` or via GraphQL. From `rails c`: - -```ruby + ```ruby project = ::Project.find_by_full_path("path-to/your-awesome-project") agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step -``` + ``` -or using GraphQL: +- Through GraphQL: **(PREMIUM ONLY)** -with this approach, you'll need a premium license to use this feature. - -If you are new to using the GitLab GraphQL API please refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md) or check out the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). - -```json + ```graphql mutation createAgent { createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { clusterAgent { @@ -141,37 +146,77 @@ If you are new to using the GitLab GraphQL API please refer to the [Getting star errors } } -``` + ``` -Note that GraphQL will only show you the token once, after you've created it. + NOTE: **Note:** + GraphQL only displays the token once, after creating it. -### Creating the Kubernetes secret + If you are new to using the GitLab GraphQL API, refer to the + [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), + or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). -Once the token has been generated it needs to be applied to the Kubernetes cluster. +### Create the Kubernetes secret -If you didn't previously define or create a namespace you need to do that first: +After generating the token, you must apply it to the Kubernetes cluster. -```shell -kubectl create namespace <YOUR-DESIRED-NAMESPACE> -``` +1. If you haven't previous defined or created a namespace, run the following command: + + ```shell + kubectl create namespace <YOUR-DESIRED-NAMESPACE> + ``` + +1. Run the following command to create your Secret: -Run the following command to create your Secret: + ```shell + kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' + ``` + +### Install the Agent into the cluster + +Next, install the in-cluster component of the Agent. This example file contains the +Kubernetes resources required for the Agent to be installed. You can modify this +example [`resources.yml` file](#example-resourcesyml-file) in the following ways: + +- You can replace `gitlab-agent` with `<YOUR-DESIRED-NAMESPACE>`. +- For the `kas-address` (Kubernetes Agent Server), the agent can use the WebSockets + or gRPC protocols to connect to the Agent Server. Depending on your cluster + configuration and GitLab architecture, you may need to use one or the other. + For the `gitlab-kas` Helm chart, an Ingress is created for the Agent Server using + the `/-/kubernetes-agent` endpoint. This can be used for the WebSockets protocol connection. + - Specify the `grpc` scheme (such as `grpc://gitlab-kas:5005`) to use gRPC directly. + Encrypted gRPC is not supported yet. Follow the + [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) + for progress updates. + - Specify the `ws` scheme (such as `ws://gitlab-kas-ingress:80/-/kubernetes-agent`) + to use an unencrypted WebSockets connection. + - Specify the `wss` scheme (such as `wss://gitlab-kas-ingress:443/-/kubernetes-agent`) + to use an encrypted WebSockets connection. This is the recommended option if + installing the Agent into a separate cluster from your Agent Server. +- If you defined your own secret name, replace `gitlab-agent-token` with your secret name. + +To apply this file, run the following command: ```shell -kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +kubectl apply -n gitlab-agent -f ./resources.yml ``` -### Installing the Agent into the cluster - -Next you are now ready to install the in-cluster component of the Agent. The below is an example YAML file of the Kubernetes resources required for the Agent to be installed. +To review your configuration, run the following command: -Let's highlight a few of the details in the example below: +```shell +$ kubectl get pods --all-namespaces -1. You can replace `gitlab-agent` with <YOUR-DESIRED-NAMESPACE> -1. For the `kas-address` (Kubernetes Agent Server), you can replace `grpc://host.docker.internal:5005` with the address of the kas agent that was initialized via your Helm install. -1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name. +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s +kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m +kube-system etcd-minikube 1/1 Running 0 14m +kube-system kube-apiserver-minikube 1/1 Running 0 14m +kube-system kube-controller-manager-minikube 1/1 Running 0 14m +kube-system kube-proxy-j6zdh 1/1 Running 0 14m +kube-system kube-scheduler-minikube 1/1 Running 0 14m +kube-system storage-provisioner 1/1 Running 0 14m +``` -`./resources.yml` +#### Example `resources.yml` file ```yaml apiVersion: v1 @@ -200,7 +245,7 @@ spec: args: - --token-file=/config/token - --kas-address - - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} volumeMounts: - name: token-volume mountPath: /config @@ -268,37 +313,31 @@ subjects: - name: gitlab-agent kind: ServiceAccount namespace: gitlab-agent - ``` -```shell -kubectl apply -n gitlab-agent -f ./resources.yml -``` +### Create a `manifest.yaml` + +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. + +Each time you commit and push a change to this file, the Agent logs the change: ```plaintext -$ kubectl get pods --all-namespaces -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s -kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m -kube-system etcd-minikube 1/1 Running 0 14m -kube-system kube-apiserver-minikube 1/1 Running 0 14m -kube-system kube-controller-manager-minikube 1/1 Running 0 14m -kube-system kube-proxy-j6zdh 1/1 Running 0 14m -kube-system kube-scheduler-minikube 1/1 Running 0 14m -kube-system storage-provisioner 1/1 Running 0 14m +2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea ``` -### Creating a `manifest.yaml` - -In the above step, you configured a `config.yaml` to point to which GitLab projects the Agent should synchronize. Within each one of those projects, you need to create a `manifest.yaml` file which the Agent will monitor. This `manifest.yaml` can be autogenerated by a templating engine or other means. +#### Example `manifest.yaml` file -Example `manifest.yaml`: +This file creates a simple NGINX deployment. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment + namespace: gitlab-agent # Can be any namespace managed by you that the agent has access to. spec: selector: matchLabels: @@ -316,14 +355,9 @@ spec: - containerPort: 80 ``` -The above file creates a simple NGINX deployment. - -Each time you commit and push a change to the `manifest.yaml` the Agent will observe the change. Example log: - -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - ## Example projects -Basic GitOps example deploying NGINX: [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent), [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +This basic GitOps example deploys NGINX: + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) |