mirror of
https://gitlab.com/gitlab-org/gitlab-foss.git
synced 2025-08-20 14:11:11 +00:00
Add latest changes from gitlab-org/gitlab@master
This commit is contained in:
GitLab Bot
@ -14,6 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
|
||||
|
||||
WARNING:
|
||||
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/406545) in GitLab 16.2. You should use the [Flux integration](../gitops.md) for GitOps.
|
||||
See [Migrate from legacy GitOps to Flux](migrate_to_flux.md).
|
||||
|
||||
This diagram shows the repositories and main actors in a GitOps deployment:
|
||||
|
||||
@ -37,89 +38,6 @@ sequenceDiagram
|
||||
|
||||
For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture).
|
||||
|
||||
## Migrate to Flux
|
||||
|
||||
You should migrate your legacy GitOps deployments so they can be
|
||||
deployed with Flux. To migrate, configure Flux to deploy manifests
|
||||
with Kustomize. If you don't have a `kustomization.yaml` file in
|
||||
the given path, it is generated automatically.
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- A configuration like:
|
||||
|
||||
```yaml
|
||||
manifest_projects:
|
||||
- id: my-group/my-project
|
||||
default_namespace: production
|
||||
paths:
|
||||
- glob: 'environments/production/**/*.yaml'
|
||||
```
|
||||
|
||||
- A [Flux installation](https://fluxcd.io/flux/installation/) with manifests in `environments/flux-system`.
|
||||
- You use a deploy token to access GitLab.
|
||||
- Your cluster can access GitLab over HTTPS.
|
||||
|
||||
To migrate:
|
||||
|
||||
1. Create a file called `environments/flux-system/production.yaml` with the following contents:
|
||||
|
||||
```yaml
|
||||
# This manifest was generated by flux. DO NOT EDIT.
|
||||
---
|
||||
apiVersion: source.toolkit.fluxcd.io/v1
|
||||
kind: GitRepository
|
||||
metadata:
|
||||
name: production
|
||||
namespace: flux-system
|
||||
spec:
|
||||
interval: 1m0s
|
||||
ref:
|
||||
branch: main
|
||||
secretRef:
|
||||
name: gitlab-deploy-token
|
||||
url: https://gitlab.example.com/my-group/my-project.git
|
||||
---
|
||||
apiVersion: kustomize.toolkit.fluxcd.io/v1
|
||||
kind: Kustomization
|
||||
metadata:
|
||||
name: production
|
||||
namespace: flux-system
|
||||
spec:
|
||||
interval: 10m0s
|
||||
path: ./environments/production
|
||||
prune: true
|
||||
sourceRef:
|
||||
kind: GitRepository
|
||||
name: production
|
||||
```
|
||||
|
||||
1. Optional. Because `agentk` uses the `default_namespace` by default, you might need to add a `kustomization.yaml` file to `/environments/production/` and list the relevant resources.
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
namespace: default
|
||||
resources:
|
||||
- relative/path/to-your/resource-1.yaml
|
||||
- relative/path/to-your/resource-2.yaml
|
||||
```
|
||||
|
||||
When you commit the `kustomization.yaml` file to the repository, a reconciliation with Flux and `agentk` is triggered.
|
||||
Because `agentk` can't handle the Kustomization file, it logs errors when you commit the file.
|
||||
|
||||
1. To ensure Flux has taken over the management of the resource, check for the resource in the `status.inventory` value of the `production` Flux Kustomization object:
|
||||
|
||||
```shell
|
||||
kubectl get kustomization production -n flux-system -o json | jq '.status.inventory.entries'
|
||||
```
|
||||
|
||||
1. Remove the entry from the `manifest_projects` list.
|
||||
|
||||
After you migrate, your GitOps deployments deploy with Flux.
|
||||
To get the most out of your Flux integration, see the [Flux Kustomization CRD](https://fluxcd.io/flux/components/kustomize/kustomization/) and [GitLab Flux documentation](../gitops.md).
|
||||
|
||||
## GitOps workflow steps
|
||||
|
||||
To update a Kubernetes cluster by using GitOps, complete the following steps.
|
||||
|
||||
148
doc/user/clusters/agent/gitops/migrate_to_flux.md
Normal file
148
doc/user/clusters/agent/gitops/migrate_to_flux.md
Normal file
@ -0,0 +1,148 @@
|
||||
---
|
||||
stage: Deploy
|
||||
group: Environments
|
||||
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
||||
---
|
||||
|
||||
# Migrate from legacy GitOps to Flux **(FREE ALL)**
|
||||
|
||||
Most users can migrate from their [legacy agent-based GitOps solution](agent.md)
|
||||
to Flux without additional work or downtime. In most cases, Flux can
|
||||
take over existing workloads without any restarts.
|
||||
|
||||
## Example GitOps configuration
|
||||
|
||||
Your legacy GitOps setup might contain an agent configuration like:
|
||||
|
||||
```yaml
|
||||
gitops:
|
||||
manifest_projects:
|
||||
- id: <your-group>/<your-repository>
|
||||
paths:
|
||||
- glob: 'manifests/*.yaml'
|
||||
```
|
||||
|
||||
The `manifests` directory referenced in the `paths.glob` might have two
|
||||
manifests. One manifest defines a `Namespace`:
|
||||
|
||||
```yaml
|
||||
# /manifests/namespace.yaml
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: production
|
||||
```
|
||||
|
||||
And the other manifest defines a `Deployment`:
|
||||
|
||||
```yaml
|
||||
# /manifests/deployment.yaml
|
||||
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: nginx-deployment
|
||||
namespace: production
|
||||
labels:
|
||||
app: nginx
|
||||
spec:
|
||||
replicas: 3
|
||||
selector:
|
||||
matchLabels:
|
||||
app: nginx
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: nginx
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.14.2
|
||||
ports:
|
||||
- containerPort: 80
|
||||
```
|
||||
|
||||
The topics on this page use this configuration to
|
||||
demonstrate a migration to Flux.
|
||||
|
||||
## Disable legacy GitOps functionality in the agent
|
||||
|
||||
When the GitOps configuration is removed, the agent
|
||||
doesn't delete any running workloads it applied.
|
||||
To remove the GitOps functionality from your agent:
|
||||
|
||||
- Delete the `gitops` section from the agent configuration file.
|
||||
|
||||
You still need a functional agent,
|
||||
so don't delete your entire `config.yaml` file.
|
||||
|
||||
If you have multiple items under `gitops.manifest_projects` or under the `paths` list, you can migrate one part at a time by removing only the specific project or path.
|
||||
|
||||
## Bootstrap Flux
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- You disabled the GitOps functionality in your agent.
|
||||
- You installed the Flux CLI in a terminal with access to your cluster.
|
||||
|
||||
To bootstrap Flux:
|
||||
|
||||
- In your terminal, run the `flux bootstrap gitlab` command. For example:
|
||||
|
||||
```shell
|
||||
flux bootstrap gitlab \
|
||||
--owner=<your-group> \
|
||||
--repository=<your-repository> \
|
||||
--branch=main \
|
||||
--path=manifests/ \
|
||||
--deploy-token-auth
|
||||
```
|
||||
|
||||
Flux is installed on your cluster, and the necessary
|
||||
Flux configuration files are committed to `manifests/flux-system`,
|
||||
which syncs Flux and the entire `manifests` directory.
|
||||
|
||||
Because the workloads (the `Namespace` and `Deployment` manifests)
|
||||
are already declared in the `manifests` directory, there is
|
||||
no extra work involved.
|
||||
|
||||
For more information about configuring Flux with GitLab, see
|
||||
[Tutorial: Set up Flux for GitOps](flux_tutorial.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `flux bootstrap` doesn't reconcile manifests correctly
|
||||
|
||||
The `flux bootstrap` command creates a `kustomizations.kustomize.toolkit.fluxcd.io`
|
||||
resource that points to the `manifests` directory.
|
||||
This resource applies to all the Kubernetes manifests in the directory,
|
||||
without requiring a [Kustomization file](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#kustomization).
|
||||
|
||||
This process might not work with your configuration.
|
||||
To troubleshoot, review the Flux Kustomization status for potential issues:
|
||||
|
||||
```shell
|
||||
kubectl get kustomizations.kustomize.toolkit.fluxcd.io -n flux-system
|
||||
```
|
||||
|
||||
### Use a `default_namespace` in the agent configuration
|
||||
|
||||
You might encounter an issue if your legacy agent-based GitOps setup
|
||||
refers to a `default_namespace` in the agent configuration, but omits this
|
||||
namespace in the manifests itself. This causes an error where
|
||||
your bootstrapped Flux doesn't know that your existing manifests are applied
|
||||
to the `default_namespace`.
|
||||
|
||||
To solve this issue, you can either:
|
||||
|
||||
- Set the namespace manually in your previously existing resource YAML.
|
||||
- Move your resources into a dedicated directory, and point Flux at it with `kustomize.toolkit.fluxcd.io/Kustomization`, where `spec.targetNamespace` specifies the namespace.
|
||||
- Move the resources into a subdirectory and add a `kustomization.yaml` file that sets the `spec.namespace` property.
|
||||
|
||||
If you prefer to move the resources outside the path already configured for Flux,
|
||||
you should use `kustomize.toolkit.fluxcd.io/Kustomization`.
|
||||
If you prefer to move the resources into a subdirectory of a path already watched by
|
||||
Flux, you should use a `kustomize.config.k8s.io/Kustomization`.
|
||||
Reference in New Issue
Block a user