diff options
Diffstat (limited to 'doc/user/clusters')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_tunnel.md | 67 | ||||
| -rw-r--r-- | doc/user/clusters/agent/index.md | 62 | ||||
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 11 | ||||
| -rw-r--r-- | doc/user/clusters/applications.md | 16 | ||||
| -rw-r--r-- | doc/user/clusters/integrations.md | 6 | ||||
| -rw-r--r-- | doc/user/clusters/management_project.md | 15 | ||||
| -rw-r--r-- | doc/user/clusters/management_project_template.md | 16 | ||||
| -rw-r--r-- | doc/user/clusters/migrating_from_gma_to_project_template.md | 6 |
8 files changed, 129 insertions, 70 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md new file mode 100644 index 00000000000..1f794bac37f --- /dev/null +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -0,0 +1,67 @@ +--- +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/#assignments +--- + +# CI/CD Tunnel + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. + +The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network +connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. + +Only CI/CD jobs set in the configuration project can access one of the configured agents. + +Prerequisites: + +- A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server). +- A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file + installed (`.gitlab/agents/<agent-name>/config.yaml`). +- An [Agent record](index.md#create-an-agent-record-in-gitlab). +- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster). + +To access your cluster from a CI/CD job through the tunnel: + +1. In your `.gitlab-ci.yml` add a section that creates a `kubectl` compatible configuration file (`kubecontext`) and use it in one + or more jobs: + + ```yaml + variables: + AGENT_ID: 4 # agent id that you got when you created the agent record + KUBE_CFG_FILE: "$CI_PROJECT_DIR/.kubeconfig.agent.yaml" + + .kubectl_config: &kubectl_config + - | + cat << EOF > "$KUBE_CFG_FILE" + apiVersion: v1 + kind: Config + clusters: + - name: agent + cluster: + server: https://kas.gitlab.com/k8s-proxy/ + users: + - name: agent + user: + token: "ci:$AGENT_ID:$CI_JOB_TOKEN" + contexts: + - name: agent + context: + cluster: agent + user: agent + current-context: agent + EOF + + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - *kubectl_config + - kubectl --kubeconfig="$KUBE_CFG_FILE" get pods + ``` + +1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created. + +We are working on [creating the configuration file automatically](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) +to simplify the process. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 414ed8377db..83933524fd4 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Kubernetes Agent **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -> - [In GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300960), KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6, `grpcs` is supported. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. > - Introduced in GitLab 13.11, the GitLab Kubernetes Agent became available to every project on GitLab.com. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) @@ -16,13 +17,14 @@ tasks in a secure and cloud-native way. It enables: - 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). +- Pull-based GitOps deployments. +- [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. - Real-time access to API endpoints in a cluster. - Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy). +- [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) -and [our development documentation](../../../development/agent/index.md). +and [our development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). ## GitLab Agent GitOps workflow @@ -37,7 +39,9 @@ sequenceDiagram participant M as Manifest repository participant K as Kubernetes Agent participant C as Agent configuration repository - K->C: Grab the configuration + loop Regularly + K-->>C: Grab the configuration + end D->>+A: Pushing code changes A->>M: Updating manifest loop Regularly @@ -246,12 +250,11 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `your-namespace` - is the namespace where the chart was installed. 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. - - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. + is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` + is the namespace where the chart was installed. + - Specify the `grpcs` scheme to use an encrypted gRPC connection. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the + `kas-address` for `wss` and `ws` schemes to whatever you need. Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) to learn more about it. - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. @@ -447,42 +450,21 @@ There are several components that work in concert for the Agent to generate the - A working Kubernetes cluster. - Cilium integration through either of these options: - - Installation through [GitLab Managed Apps](../applications.md#install-cilium-using-gitlab-cicd). + - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an existing installation. - One or more network policies through any of these options: - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies. - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration. - Add the required labels and annotations to existing network policies. -- Use a configuration repository to inform the Agent through a `config.yaml` file, which - repositories can synchronize with. This repository might be the same, or a separate GitLab - project. +- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) The setup process follows the same steps as [GitOps](#get-started-with-gitops-and-the-gitlab-agent), with the following differences: -- When you define a configuration repository, you must do so with [Cilium settings](#define-a-configuration-repository-with-cilium-settings). +- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). - You do not need to specify the `gitops` configuration section. -### Define a configuration repository with Cilium settings - -You need a GitLab repository to contain your Agent configuration. The minimal repository layout -looks like this: - -```plaintext -.gitlab/agents/<agent-name>/config.yaml -``` - -Your `config.yaml` file must specify the `host` and `port` of your Hubble Relay service. If your -Cilium integration was performed through [GitLab Managed Apps](../applications.md#install-cilium-using-gitlab-cicd), -you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80`: - -```yaml -cilium: - hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>" - ... -``` - ## Management interfaces Users with at least the [Developer](../../permissions.md) can access the user interface @@ -516,9 +498,17 @@ This error is shown if there are some connectivity issues between the address specified as `kas-address`, and your Agent pod. To fix it, make sure that you specified the `kas-address` correctly. +```json +{"level":"error","time":"2021-06-25T21:15:45.335Z","msg":"Reverse tunnel","mod_name":"reverse_tunnel","error":"Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""} +``` + +This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the +`wss` or `ws` URL ends with a training slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` +or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. + ### Agent logs - ValidationError(Deployment.metadata) -```plaintext +```json {"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"} ``` diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index cd40cc6810e..a3a3e4c29b0 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -51,6 +51,7 @@ gitops: # in YAML or JSON format. - id: gitlab-org/cluster-integration/gitlab-agent # Namespace to use if not set explicitly in object manifest. + # Also used for inventory ConfigMap objects. default_namespace: my-ns # Paths inside of the repository to scan for manifest files. # Directories with names starting with a dot are ignored. @@ -84,13 +85,13 @@ gitops: # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470 # Can be: orphan, background, foreground prune_propagation_policy: foreground # 'foreground' by default - # InventoryPolicy defines if an inventory object can take over + # Inventory policy defines if an inventory object can take over # objects that belong to another inventory object or don't # belong to any inventory object. # This is done by determining if the apply/prune operation # can go through for a resource based on the comparison # the inventory-id value in the package and the owning-inventory - # annotation in the live object. + # annotation (config.k8s.io/owning-inventory) in the live object. # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66 # Can be: must_match, adopt_if_no_inventory, adopt_all inventory_policy: must_match # 'must_match' by default @@ -157,7 +158,9 @@ cilium: hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>" ``` -If your Cilium integration was performed through GitLab Managed Apps, you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80` as the address: +If your Cilium integration was performed through [GitLab Managed Apps](../applications.md#install-cilium-using-gitlab-cicd) or the +[cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium), +you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80` as the address: ```yaml cilium: diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index a6aa4e00005..5d247f04d3b 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -90,7 +90,7 @@ To install applications using GitLab CI/CD: 1. Optionally, define `.gitlab/managed-apps/<application>/values.yaml` file to customize values for the installed application. -A GitLab CI/CD pipeline runs on the `master` branch to install the +A GitLab CI/CD pipeline runs on the default branch to install the applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). @@ -391,16 +391,16 @@ For GitLab Runner to function, you _must_ specify the following: - `gitlabUrl`: The GitLab server full URL (for example, `https://gitlab.example.com`) to register the Runner against. - `runnerRegistrationToken`: The registration token for adding new runners to GitLab. - This must be [retrieved from your GitLab instance](../../ci/runners/README.md). + This must be [retrieved from your GitLab instance](../../ci/runners/index.md). -These values can be specified using [CI/CD variables](../../ci/variables/README.md): +These values can be specified using [CI/CD variables](../../ci/variables/index.md): - `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `.gitlab/managed-apps/gitlab-runner/values.yaml`. If you choose to use CI variables, comment out or remove `runnerRegistrationToken:` and `runnerToken:` from `.gitlab/managed-apps/gitlab-runner/values`. -The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../ci/variables/README.md#protect-a-cicd-variable) and [masked variable](../../ci/variables/README.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml` file. +The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml` file. You can customize the installation of GitLab Runner by defining `.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster @@ -440,8 +440,8 @@ cilium: The `clusterType` variable enables the recommended Helm variables for a corresponding cluster type. You can check the recommended variables for each cluster type in the official documentation: -- [Google GKE](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#deploy-cilium) -- [AWS EKS](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-eks/#deploy-cilium) +- [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) +- [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). @@ -460,7 +460,7 @@ You can check Cilium's installation status on the cluster management page: WARNING: Installation and removal of the Cilium requires a **manual** -[restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) +[restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-helm/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are [managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. Whenever Hubble is enabled, its related pod might require a @@ -762,7 +762,7 @@ Set: - "Redirect URI" to `http://<JupyterHub Host>/hub/oauth_callback`. - "Scope" to `api read_repository write_repository`. -In addition, the following variables must be specified using [CI/CD variables](../../ci/variables/README.md): +In addition, the following variables must be specified using [CI/CD variables](../../ci/variables/index.md): - `JUPYTERHUB_PROXY_SECRET_TOKEN` - Secure string used for signing communications from the hub. Read [`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken). diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 6c87efaf5a3..d2861ce2946 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -88,7 +88,7 @@ To enable the Prometheus integration for your cluster: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61077) in GitLab 13.12. You can integrate your cluster with [Elastic -Stack](https://www.elastic.co/elastic-stack) to index and [query your pod +Stack](https://www.elastic.co/elastic-stack/) to index and [query your pod logs](../project/clusters/kubernetes_pod_logs.md). ### Elastic Stack Prerequisites @@ -119,7 +119,7 @@ wget https://gitlab.com/gitlab-org/project-templates/cluster-management/-/raw/ma helm repo add gitlab https://charts.gitlab.io # Install Elastic Stack -helm install prometheus gitlab/elastic-stack -n gitlab-managed-apps --values values.yaml +helm install elastic-stack gitlab/elastic-stack -n gitlab-managed-apps --values values.yaml ``` ### Enable Elastic Stack integration for your cluster @@ -134,6 +134,6 @@ To enable the Elastic Stack integration for your cluster: - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's **Kubernetes** page. 1. Select the **Integrations** tab. -1. Check the **Enable Prometheus integration** checkbox. +1. Check the **Enable Elastic Stack integration** checkbox. 1. Click **Save changes**. 1. Go to the **Health** tab to see your cluster's metrics. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f741ab2d95a..204afa9fc89 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -22,7 +22,7 @@ This can be useful for: ## Permissions Only the management project receives `cluster-admin` privileges. All -other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). +other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/cluster_access.md#rbac-cluster-resources). Management projects are restricted to the following: @@ -45,12 +45,11 @@ To use a cluster management project for a cluster: To select a cluster management project to use: 1. Navigate to the appropriate configuration page. For a: - - [Project-level cluster](../project/clusters/index.md), navigate to your project's + - [Project-level cluster](../project/clusters/index.md), go to your project's **Infrastructure > Kubernetes clusters** page. - - [Group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** - page. - - [Instance-level cluster](../instance/clusters/index.md), navigate to Admin Area's **Kubernetes** + - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. + - [Instance-level cluster](../instance/clusters/index.md), go to **Menu >** **{admin}** **Admin > Kubernetes** page. 1. Select the project using **Cluster management project field** in the **Advanced settings** section. @@ -59,7 +58,7 @@ To select a cluster management project to use: ### Configuring your pipeline After designating a project as the management project for the cluster, -write a [`.gitlab-ci.yml`](../../ci/yaml/README.md) in that project. For example: +write a [`.gitlab-ci.yml`](../../ci/yaml/index.md) in that project. For example: ```yaml configure cluster: @@ -72,7 +71,7 @@ configure cluster: ### Setting the environment scope [Environment -scopes](../project/clusters/index.md#setting-the-environment-scope) +scopes](../project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope) are usable when associating multiple clusters to the same management project. @@ -88,7 +87,7 @@ to a management project: | Production | `production` | The following environments set in -[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the +[`.gitlab-ci.yml`](../../ci/yaml/index.md) deploy to the Development, Staging, and Production cluster respectively. ```yaml diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 52390cb18b0..eb86c1702cc 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -18,10 +18,10 @@ need, or even add new ones that are not built-in. ## How to use this template -1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). +1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). 1. Make this project a [cluster management project](management_project.md). 1. If you used the [GitLab Managed Apps](applications.md), refer to - [Migrating from GitLab Manged Apps](migrating_from_gma_to_project_template.md). + [Migrating from GitLab Managed Apps](migrating_from_gma_to_project_template.md). ### Components @@ -37,10 +37,10 @@ In the repository of the newly-created project, you will find: The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): -- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 - releases for a given namespace. If so, it will fail the pipeline and ask you to manually +- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 + releases for a given namespace. If so, it will fail the pipeline and ask you to manually [migrate your Helm v2 releases to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/). -- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label +- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label for the [Cilium](https://github.com/cilium/cilium/) app network policies to work. - `gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to facilitate the GitLab Managed Apps adoption. @@ -50,7 +50,7 @@ project. This image consists of a set of Bash utility scripts to support [Helm v #### The main `helmfile.yml` file -This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment +This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment the paths for the apps that you would like to manage. By default, each `helmfile.yaml` in these sub-paths will have the attribute `installed: true`, which signifies that everytime @@ -58,7 +58,7 @@ the pipeline runs, Helmfile will try to either install or update your apps accor cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile will try to uninstall this app from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. -Furthermore, each app has an `applications/{app}/values.yaml` file. This is the +Furthermore, each app has an `applications/{app}/values.yaml` file. This is the place where you can define some default values for your app's Helm chart. Some apps will already have defaults pre-defined by GitLab. @@ -82,5 +82,5 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp ### Migrating from GitLab Managed Apps -If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to +If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to [migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index 7fa6ccea433..dc16cf5cc45 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -35,9 +35,9 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig applications that you would like to manage with this project. Although you could uncomment all the ones you want to managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during the process. -1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed +1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed for your app. Take a GitLab Runner Helm v3 release as an example: - + The following command lists the releases and their versions: ```shell @@ -83,7 +83,7 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig 1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any unexpected updates. - + Some annotation checksums are expected to be updated, as well as this attribute: ```diff |