Commit 37de2aa4 authored by Amy Qualls's avatar Amy Qualls

Merge branch 'nagyv-gitlab-master-patch-04186' into 'master'

Added version compatibility instructions + reorg

See merge request gitlab-org/gitlab!46779
parents e7e53ab3 e3ac1b22
...@@ -24,9 +24,11 @@ tasks in a secure and cloud-native way. It enables: ...@@ -24,9 +24,11 @@ tasks in a secure and cloud-native way. It enables:
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 ## GitLab Agent GitOps workflow
### GitLab Agent GitOps workflow The GitLab Agent uses multiple GitLab projects to provide a flexible workflow
that can suit various needs. This diagram shows these repositories and the main
actors involved in a deployment:
```mermaid ```mermaid
sequenceDiagram sequenceDiagram
...@@ -44,11 +46,6 @@ sequenceDiagram ...@@ -44,11 +46,6 @@ sequenceDiagram
end end
``` ```
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
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:
- A properly-configured Kubernetes cluster. - A properly-configured Kubernetes cluster.
...@@ -57,15 +54,43 @@ There are several components that work in concert for the Agent to accomplish Gi ...@@ -57,15 +54,43 @@ There are several components that work in concert for the Agent to accomplish Gi
- A manifest repository that contains a `manifest.yaml`, which is tracked by the - 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. Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster.
These repositories might be the same GitLab project or separate projects.
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
The setup process involves a few steps to enable GitOps deployments: The setup process involves a few steps to enable GitOps deployments:
1. Installing the Agent server. 1. Installing the Agent server. This must be done one time for every GitLab installation.
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`.
### Upgrades and version compatibility
As the GitLab Kubernetes Agent is a new product, we are constantly adding new features
to it. As a result, while shipped features are production ready, its internal API is
neither stable nor versioned yet. For this reason, GitLab only guarantees compatibility
between corresponding major.minor (X.Y) versions of GitLab and its cluster side
component, `agentk`.
Upgrade your agent installations together with GitLab upgrades: if you install
GitLab version 13.6, use version 13.6.x versions of `agentk`.
The available `agentk` versions can be found in
[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==).
### Upgrades and Version compatibility
As the GitLab Kubernetes Agent is a new product, we are constantly adding new features to it. As a result, while shipped features are production ready, it's internal API is not stable nor versioned yet. For this reason, we only guarantee compatibility between corresponding major.minor versions of GitLab and its cluster side component, `agentk`. Please, upgrade your agent installations together with GitLab upgrades.
Example: having GitLab 13.6 installed, please use version 13.6.x versions of `agentk`.
The available `agentk` versions can be found in [its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==).
### Install the Kubernetes Agent Server ### Install the Kubernetes Agent Server
The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus
...@@ -77,6 +102,8 @@ documentation](https://docs.gitlab.com/ee/install/README.html). ...@@ -77,6 +102,8 @@ documentation](https://docs.gitlab.com/ee/install/README.html).
NOTE: **Note:** NOTE: **Note:**
GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834).
#### Install with Omnibus
When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package: When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package:
1. Edit `/etc/gitlab/gitlab.rb`: 1. Edit `/etc/gitlab/gitlab.rb`:
...@@ -87,6 +114,8 @@ gitlab_kas['enable'] = true ...@@ -87,6 +114,8 @@ gitlab_kas['enable'] = true
1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). 1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure).
#### Install with the Helm chart
When installing or upgrading the GitLab Helm chart, consider the following Helm v3 example. When installing or upgrading the GitLab Helm chart, consider the following Helm v3 example.
If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm). If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm).
......
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