diff options
Diffstat (limited to 'doc/user/clusters/agent/gitops/flux.md')
-rw-r--r-- | doc/user/clusters/agent/gitops/flux.md | 63 |
1 files changed, 62 insertions, 1 deletions
diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md index 98840080716..f0a681c1a5c 100644 --- a/doc/user/clusters/agent/gitops/flux.md +++ b/doc/user/clusters/agent/gitops/flux.md @@ -13,9 +13,13 @@ You can use Flux to: - Reconcile code changes with your deployments. - Manage your Flux installation itself with a bootstrap. +You can use the agent for Kubernetes with Flux to: + +- Trigger immediate Git repository reconciliation. + To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). -Support for Flux is in [Beta](../../../../policy/alpha-beta-support.md#beta). +Support for Flux is in [Beta](../../../../policy/experiment-beta-support.md#beta). ## Bootstrap installation @@ -34,3 +38,60 @@ write access to the source repositories. ## GitOps repository structure You should organize your repositories to meet the needs of your team. For detailed recommendations, see the Flux [repository structure documentation](https://fluxcd.io/flux/guides/repository-structure/). + +## Immediate Git repository reconciliation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1. + +Usually, the Flux source controller reconciles Git repositories at configured intervals. +This can cause delays between a `git push` and the reconciliation of the cluster state, and results in +unnecessary pulls from GitLab. + +The agent for Kubernetes automatically detects Flux `GitRepository` objects that +reference GitLab projects in the instance the agent is connected to, +and configures a [`Receiver`](https://fluxcd.io/flux/components/notification/receiver/) for the instance. +When the agent for Kubernetes detects a `git push`, the `Receiver` is triggered +and Flux reconciles the cluster with any changes to the repository. + +To use immediate Git repository reconciliation, you must have a Kubernetes cluster that runs: + +- The agent for Kubernetes. +- Flux `source-controller` and `notification-controller`. + +Immediate Git repository reconciliation can reduce the time between a push and reconciliation, +but it doesn't guarantee that every `git push` event is received. You should still set +[`GitRepository.spec.interval`](https://fluxcd.io/flux/components/source/gitrepositories/#interval) +to an acceptable duration. + +### Custom webhook endpoints + +When the agent for Kubernetes calls the `Receiver` webhook, +the agent defaults to `http://webhook-receiver.flux-system.svc.cluster.local`, +which is also the default URL set by a Flux bootstrap installation. To configure a custom +endpoint, set `flux.webhook_receiver_url` to a URL that the agent can resolve. For example: + +```yaml +flux: + webhook_receiver_url: http://webhook-receiver.another-flux-namespace.svc.cluster.local +``` + +There is special handing for +[service proxy URLs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster-services/) configured +in this format: `/api/v1/namespaces/[^/]+/services/[^/]+/proxy`. For example: + +```yaml +flux: + webhook_receiver_url: /api/v1/namespaces/flux-system/services/http:webhook-receiver:80/proxy +``` + +In these cases, the agent for Kubernetes uses the available Kubernetes configuration +and context to connect to the API endpoint. +You can use this if you run an agent outside a cluster +and you haven't [configured an `Ingress`](https://fluxcd.io/flux/guides/webhook-receivers/#expose-the-webhook-receiver) +for the Flux notification controller. + +WARNING: +You should configure only trusted service proxy URLs. +When you provide a service proxy URL, +the agent for Kubernetes sends typical Kubernetes API requests which include +the credentials necessary to authenticate with the API service. |