Skip to content

G
gitlab-ce
Commit da833f99 authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs-aqualls-clean-agent-page' into 'master' 

Tidy Kubernetes agent page for tone and style

See merge request gitlab-org/gitlab!43063
parents 8d299cf9 aa87981a
Hide whitespace changes
Inline Side-by-side
Showing with 130 additions and 110 deletions
doc/user/clusters/agent/index.md
View file @ da833f99
...@@ -8,14 +8,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -8,14 +8,17 @@ 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. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
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 Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329).
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).
## Architecture ## Architecture
...@@ -37,34 +40,42 @@ sequenceDiagram ...@@ -37,34 +40,42 @@ sequenceDiagram
end 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: There are several components that work in concert for the Agent to accomplish GitOps deployments:
1. A Kubernetes cluster that is properly configured - A properly-configured Kubernetes cluster.
1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with. - A configuration repository that contains a `config.yaml` file, which tells the
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. 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. Installing the Agent server via GitLab Helm chart.
1. Defining a configuration directory 1. Defining a configuration directory.
1. Creating an Agent record in GitLab 1. Creating an Agent record in GitLab.
1. Generating and copying a Secret token used to connect to the Agent 1. Generating and copying a Secret token used to connect to the Agent.
1. Installing the Agent into the cluster 1. Installing the Agent into the cluster.
1. Creating a `manifest.yaml` 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](https://gitlab.com/gitlab-org/gitlab/-/issues/223060)
in the official Linux Package.
If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/) 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`
When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify): for the Agent to be properly installed and configured:
```shell ```shell
helm upgrade --force --install gitlab . \ helm upgrade --force --install gitlab . \
...@@ -76,15 +87,14 @@ helm upgrade --force --install gitlab . \ ...@@ -76,15 +87,14 @@ helm upgrade --force --install gitlab . \
--set global.kas.enabled=true --set global.kas.enabled=true
``` ```
`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured. ### Define a configuration repository
### Defining 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: ```plaintext
.gitlab/agents/<agent-name>/config.yaml
`.gitlab/agents/<agent-name>/config.yaml` ```
The `config.yaml` file contents should look like this: The `config.yaml` file contents should look like this:
...@@ -94,82 +104,104 @@ gitops: ...@@ -94,82 +104,104 @@ gitops:
- id: "path-to/your-awesome-project" - id: "path-to/your-awesome-project"
``` ```
### Creating an Agent record in GitLab ### Create 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.
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 - Through the Rails console, by running `rails c`:
1. Via GraphQL
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") project = ::Project.find_by_full_path("path-to/your-awesome-project")
agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) agent = ::Clusters::Agent.create(name: "<agent-name>", project: project)
token = ::Clusters::AgentToken.create(agent: agent) token = ::Clusters::AgentToken.create(agent: agent)
token.token # this will print out the token you need to use on the next step 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. ```json
mutation createAgent {
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). createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) {
clusterAgent {
```json id
mutation createAgent { name
createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { }
clusterAgent { errors
id
name
} }
errors
} }
}
mutation createToken {
mutation createToken { clusterAgentTokenCreate(input: { clusterAgentId: <cluster-agent-id-taken-from-the-previous-mutation> }) {
clusterAgentTokenCreate(input: { clusterAgentId: <cluster-agent-id-taken-from-the-previous-mutation> }) { secret # This is the value you need to use on the next step
secret # This is the value you need to use on the next step token {
token { createdAt
createdAt id
id }
errors
} }
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 1. If you haven't previous defined or created a namespace, run the following command:
kubectl create namespace <YOUR-DESIRED-NAMESPACE>
```
Run the following command to create your Secret: ```shell
kubectl create namespace <YOUR-DESIRED-NAMESPACE>
```
1. 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), you can replace
`grpc://host.docker.internal:5005` with the address of the `kas` agent initialized
in your Helm install.
- If you defined your own secret name, replace `gitlab-agent-token` with your secret name.
To apply this file, run the following command:
```shell ```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 To review your configuration, run the following command:
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.
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> NAMESPACE NAME READY STATUS RESTARTS AGE
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. gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s
1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name. 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 ```yaml
apiVersion: v1 apiVersion: v1
...@@ -266,31 +298,24 @@ subjects: ...@@ -266,31 +298,24 @@ subjects:
- name: gitlab-agent - name: gitlab-agent
kind: ServiceAccount kind: ServiceAccount
namespace: gitlab-agent namespace: gitlab-agent
``` ```
```shell ### Create a `manifest.yaml`
kubectl apply -n gitlab-agent -f ./resources.yml
``` 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 ```plaintext
$ kubectl get pods --all-namespaces 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
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
``` ```
### Creating a `manifest.yaml` #### Example `manifest.yaml` file
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`: This file creates a simple NGINX deployment.
```yaml ```yaml
apiVersion: apps/v1 apiVersion: apps/v1
...@@ -314,14 +339,9 @@ spec: ...@@ -314,14 +339,9 @@ spec:
- containerPort: 80 - 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 ## 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)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7