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
Show 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
> [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
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
......@@ -37,34 +40,42 @@ 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](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/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 . \
......@@ -76,15 +87,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:
......@@ -94,31 +104,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
```json
mutation createAgent {
createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) {
clusterAgent {
......@@ -139,37 +142,66 @@ 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), 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
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
......@@ -266,31 +298,24 @@ 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
......@@ -314,14 +339,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)
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