mirror of https://github.com/fluxcd/flux2.git
Merge pull request #401 from fluxcd/docs-v1-migration
Add migration guide for Flux v1 userspull/402/head
Stefan Prodan
4 years ago
committed by
GitHub
commit
fb81870803
@ -0,0 +1,315 @@
|
||||
# Migrate from Flux v1 to v2
|
||||
|
||||
This guide walks you through migrating from Flux v1 to v2.
|
||||
Read the [FAQ](../faq/index.md) to find out what differences are between v1 and v2.
|
||||
|
||||
!!! info "Automated image updates"
|
||||
The image automation feature is under development in Flux v2.
|
||||
Please consult the [roadmap](../roadmap/index.md) for more details.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You will need a Kubernetes cluster version **1.16** or newer
|
||||
and kubectl version **1.18** or newer.
|
||||
|
||||
### Install Flux v2 CLI
|
||||
|
||||
With Homebrew:
|
||||
|
||||
```sh
|
||||
brew install fluxcd/tap/flux
|
||||
```
|
||||
|
||||
With Bash:
|
||||
|
||||
```sh
|
||||
curl -s https://toolkit.fluxcd.io/install.sh | sudo bash
|
||||
|
||||
# enable completions in ~/.bash_profile
|
||||
. <(flux completion bash)
|
||||
```
|
||||
|
||||
Command-line completion for `zsh`, `fish`, and `powershell`
|
||||
are also supported with their own sub-commands.
|
||||
|
||||
Binaries for macOS, Windows and Linux AMD64/ARM are available for download on the
|
||||
[release page](https://github.com/fluxcd/flux2/releases).
|
||||
|
||||
Verify that your cluster satisfies the prerequisites with:
|
||||
|
||||
```sh
|
||||
flux check --pre
|
||||
```
|
||||
|
||||
## GitOps migration
|
||||
|
||||
Flux v2 offers an installation procedure that is declarative first
|
||||
and disaster resilient.
|
||||
|
||||
Using the `flux bootstrap` command you can install Flux on a
|
||||
Kubernetes cluster and configure it to manage itself from a Git
|
||||
repository. The Git repository created during bootstrap can be used
|
||||
to define the state of your fleet of Kubernetes clusters.
|
||||
|
||||
For a detailed walk-through of the bootstrap procedure please see the [installation guide](installation.md).
|
||||
|
||||
After you've installed Flux v2 on your cluster using bootstrap,
|
||||
you can delete the Flux v1 from your clusters and move the manifests from the
|
||||
Flux v1 repository to the bootstrap one.
|
||||
|
||||
## In-place migration
|
||||
|
||||
!!! warning
|
||||
For production use we recommend using the **bootstrap** procedure,
|
||||
but if you wish to install Flux v2 in the
|
||||
same way as Flux v1 then follow along.
|
||||
|
||||
### Flux read-only mode
|
||||
|
||||
Assuming you've installed Flux v1 to sync a directory with plain YAMLs from a private Git repo:
|
||||
|
||||
```sh
|
||||
# create namespace
|
||||
kubectl create ns flux
|
||||
|
||||
# deploy Flux v1
|
||||
fluxctl install \
|
||||
--git-url=git@github.com:org/app \
|
||||
--git-branch=main \
|
||||
--git-path=./deploy \
|
||||
--git-readonly \
|
||||
--namespace=flux | kubectl apply -f -
|
||||
|
||||
# print deploy key
|
||||
fluxctl identity --k8s-fwd-ns flux
|
||||
|
||||
# trigger sync
|
||||
fluxctl sync --k8s-fwd-ns flux
|
||||
```
|
||||
|
||||
!!! hint "Uninstall Flux v1"
|
||||
Before you proceed, scale the Flux v1 deployment to zero
|
||||
or delete its namespace and RBAC.
|
||||
|
||||
If there are YAML files in your `deploy` dir that are not meant to be
|
||||
applied on the cluster, you can exclude them by placing a `.sourceignore` in your repo root:
|
||||
|
||||
```console
|
||||
$ cat .sourceignore
|
||||
# exclude all
|
||||
/*
|
||||
# include deploy dir
|
||||
!/deploy
|
||||
# exclude files from deploy dir
|
||||
/deploy/**/eksctl.yaml
|
||||
/deploy/**/charts
|
||||
```
|
||||
|
||||
Install Flux v2 in the `flux-system` namespace:
|
||||
|
||||
```console
|
||||
$ flux install \
|
||||
--arch=amd64 \
|
||||
--network-policy=true \
|
||||
--watch-all-namespaces=true \
|
||||
--namespace=flux-systen
|
||||
✚ generating manifests
|
||||
✔ manifests build completed
|
||||
► installing components in flux-system namespace
|
||||
✔ install completed
|
||||
◎ verifying installation
|
||||
✔ source-controller ready
|
||||
✔ kustomize-controller ready
|
||||
✔ helm-controller ready
|
||||
✔ notification-controller ready
|
||||
✔ install finished
|
||||
```
|
||||
|
||||
Register your Git repository and add the deploy key with read-only access:
|
||||
|
||||
```console
|
||||
$ flux create source git app \
|
||||
--url=ssh://git@github.com/org/app \
|
||||
--branch=main \
|
||||
--interval=1m
|
||||
► generating deploy key pair
|
||||
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCp2x9ghVmv1zD...
|
||||
Have you added the deploy key to your repository: y
|
||||
► collecting preferred public key from SSH server
|
||||
✔ collected public key from SSH server:
|
||||
github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A...
|
||||
► applying secret with keys
|
||||
✔ authentication configured
|
||||
✚ generating GitRepository source
|
||||
► applying GitRepository source
|
||||
✔ GitRepository source created
|
||||
◎ waiting for GitRepository source reconciliation
|
||||
✔ GitRepository source reconciliation completed
|
||||
✔ fetched revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b
|
||||
```
|
||||
|
||||
Configure the reconciliation of the `deploy` dir on your cluster:
|
||||
|
||||
```console
|
||||
$ flux create kustomization app \
|
||||
--source=app \
|
||||
--path="./deploy" \
|
||||
--prune=true \
|
||||
--interval=10m
|
||||
✚ generating Kustomization
|
||||
► applying Kustomization
|
||||
✔ Kustomization created
|
||||
◎ waiting for Kustomization reconciliation
|
||||
✔ Kustomization app is ready
|
||||
✔ applied revision main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b
|
||||
```
|
||||
|
||||
If your repository contains secrets encrypted with Mozilla SOPS, please read this [guide](mozilla-sops.md).
|
||||
|
||||
Pull changes from Git and apply them immediately:
|
||||
|
||||
```sh
|
||||
flux reconcile kustomization app --with-source
|
||||
```
|
||||
|
||||
List all Kubernetes objects reconciled by `app`:
|
||||
|
||||
```sh
|
||||
kubectl get all --all-namespaces \
|
||||
-l=kustomize.toolkit.fluxcd.io/name=app \
|
||||
-l=kustomize.toolkit.fluxcd.io/namespace=flux-system
|
||||
```
|
||||
|
||||
### Flux with Kustomize
|
||||
|
||||
Assuming you've installed Flux v1 to sync a Kustomize overlay from an HTTPS Git repository:
|
||||
|
||||
```sh
|
||||
fluxctl install \
|
||||
--git-url=https://github.com/org/app \
|
||||
--git-branch=main \
|
||||
--manifest-generation \
|
||||
--namespace=flux | kubectl apply -f -
|
||||
```
|
||||
|
||||
With the following `.flux.yaml` in the root dir:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
patchUpdated:
|
||||
generators:
|
||||
- command: kustomize build ./overlays/prod
|
||||
patchFile: flux-patch.yaml
|
||||
```
|
||||
|
||||
!!! hint "Uninstall Flux v1"
|
||||
Before you proceed, delete the Flux v1 namespace
|
||||
and remove the `.flux.yaml` from your repo.
|
||||
|
||||
Install Flux v2 in the `flux-system` namespace:
|
||||
|
||||
```sh
|
||||
flux install
|
||||
```
|
||||
|
||||
Register the Git repository using a personal access token:
|
||||
|
||||
```sh
|
||||
flux create source git app \
|
||||
--url=https://github.com/org/app \
|
||||
--branch=main \
|
||||
--username=git \
|
||||
--password=token \
|
||||
--interval=1m
|
||||
```
|
||||
|
||||
Configure the reconciliation of the `prod` overlay on your cluster:
|
||||
|
||||
```sh
|
||||
flux create kustomization app \
|
||||
--source=app \
|
||||
--path="./overlays/prod" \
|
||||
--prune=true \
|
||||
--interval=10m
|
||||
```
|
||||
|
||||
Check the status of the Kustomization reconciliation:
|
||||
|
||||
```console
|
||||
$ flux get kustomizations app
|
||||
NAME REVISION SUSPENDED READY
|
||||
app main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b False True
|
||||
```
|
||||
|
||||
### Flux with Slack notifications
|
||||
|
||||
Assuming you've configured Flux v1 to send notifications to Slack with FluxCloud.
|
||||
|
||||
With Flux v2, create an alert provider for a Slack channel:
|
||||
|
||||
```sh
|
||||
flux create alert-provider slack \
|
||||
--type=slack \
|
||||
--channel=general \
|
||||
--address=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
|
||||
```
|
||||
|
||||
And configure notifications for the `app` reconciliation events:
|
||||
|
||||
```sh
|
||||
flux create alert app \
|
||||
--provider-ref=slack \
|
||||
--event-severity=info \
|
||||
--event-source=GitRepository/app \
|
||||
--event-source=Kustomization/app
|
||||
```
|
||||
|
||||
For more details, read the guides on how to configure
|
||||
[notifications](notifications.md) and [webhooks](webhook-receivers.md).
|
||||
|
||||
### Flux debugging
|
||||
|
||||
Check the status of Git operations:
|
||||
|
||||
```console
|
||||
$ kubectl -n flux-system get gitrepositories
|
||||
NAME READY MESSAGE
|
||||
app True Fetched revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b
|
||||
test False SSH handshake failed: unable to authenticate, attempted methods [none publickey]
|
||||
```
|
||||
|
||||
Check the status of the cluster reconciliation with kubectl:
|
||||
|
||||
```console
|
||||
$ kubectl -n flux-system get kustomizations
|
||||
NAME READY STATUS
|
||||
app True Applied revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9
|
||||
test False The Service 'backend' is invalid: spec.type: Unsupported value: 'Ingress'
|
||||
```
|
||||
|
||||
Suspend a reconciliation:
|
||||
|
||||
```console
|
||||
$ flux suspend kustomization app
|
||||
► suspending kustomization app in flux-system namespace
|
||||
✔ kustomization suspended
|
||||
```
|
||||
|
||||
Check the status with kubectl:
|
||||
|
||||
```console
|
||||
$ kubectl -n flux-system get kustomization app
|
||||
NAME READY STATUS
|
||||
app False Kustomization is suspended, skipping reconciliation
|
||||
```
|
||||
|
||||
Resume a reconciliation:
|
||||
|
||||
```console
|
||||
$ flux resume kustomization app
|
||||
► resuming Kustomization app in flux-system namespace
|
||||
✔ Kustomization resumed
|
||||
◎ waiting for Kustomization reconciliation
|
||||
✔ Kustomization reconciliation completed
|
||||
✔ applied revision main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b
|
||||
```
|
||||
Loading…
Reference in New Issue