mirror of https://github.com/fluxcd/flux2.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
242 lines
7.8 KiB
Markdown
242 lines
7.8 KiB
Markdown
# Commit based Notifications
|
|
|
|
The GitHub, GitLab, Bitbucket, and Azure DevOps providers are slightly different to the other providers. Instead of
|
|
a stateless stream of events, the git notification providers will link the event with accompanying git commit which
|
|
triggered the event. The linking is done by updating the commit status of a specific commit.
|
|
|
|
- [GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks)
|
|
- [GitLab](https://docs.gitlab.com/ee/api/commits.html)
|
|
- [Bitbucket](https://developer.atlassian.com/server/bitbucket/how-tos/updating-build-status-for-commits/)
|
|
- [Azure DevOps](https://docs.microsoft.com/en-us/rest/api/azure/devops/git/statuses?view=azure-devops-rest-6.0)
|
|
|
|
In GitHub the commit status set by notification-controller will result in a green checkmark or red cross next to the commit hash.
|
|
Clicking the icon will show more detailed information about the status.
|
|
|
|
|
|
Receiving an event in the form of a commit status has the benefit that it closes the deployment loop. This gives quick and visible feedback if a commit has reconciled and if it succeeded. This means deployments operate in a similar manner to "traditional" push based CD.
|
|
Status can be fetched from the git providers API for a specific commit. This allows for custom automation tools that can automatically promote, commit to a new directory, after receiving a successful commit status. This can all be done without requiring any access to the Kubernetes cluster
|
|
|
|
The provider works by referencing the same git repository as the Kustomization controller does.
|
|
When a new commit is pushed to the repository, source-controller will sync the commit, triggering the kustomize-controller
|
|
to reconcile the new commit. After this is done the kustomize-controller sends an event to the notification-controller
|
|
with the result and the commit hash it reconciled. Then notification-controller can update the correct commit and repository when receiving the event.
|
|
|
|
|
|
|
|
|
|
!!! hint "Limitations"
|
|
The git notification providers require that a commit hash present in the meta data
|
|
of the event. There for the the providers will only work with `Kustomization` as an
|
|
event source, as it is the only resource which includes this data.
|
|
|
|
## Prerequisites
|
|
|
|
### Authentication Token
|
|
|
|
#### Obtaining your git providers credentials
|
|
|
|
The token/app-password will need to have write access for the repository it will be updating the commit status in.
|
|
|
|
Follow the respective guide for your git provider
|
|
|
|
- [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
|
|
- [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
|
|
- [Azure DevOps personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page)
|
|
- [app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)
|
|
|
|
#### Creating Git Secret for your token/app-password
|
|
|
|
Use the following command to store the token/app-password in a secret
|
|
|
|
=== "GitHub, GitLab, Azure DevOps"
|
|
```bash
|
|
$ kubectl -n flux-system create secret generic git \
|
|
--from-literal=token='<YOURTOKEN>'
|
|
---
|
|
apiVersion: v1
|
|
data:
|
|
token: PFlPVVJUT0tFTj4=
|
|
kind: Secret
|
|
metadata:
|
|
creationTimestamp: null
|
|
name: git
|
|
namespace: flux-system
|
|
```
|
|
=== "BitBucket"
|
|
```bash
|
|
$ kubectl -n flux-system create secret generic bitbucket\
|
|
--from-literal=token='<username>:<app-password>'
|
|
---
|
|
apiVersion: v1
|
|
kind: Secret
|
|
metadata:
|
|
name: git
|
|
namespace: default
|
|
data:
|
|
token: <username>:<app-password>
|
|
```
|
|
|
|
## Creating a Deployment
|
|
|
|
Copy the manifest content in the "[kustomize](https://github.com/stefanprodan/podinfo/tree/master/kustomize)" directory
|
|
into the directory "./clusters/my-cluster/podinfo" in your fleet-infra repository. Make sure that you also add the
|
|
namespace podinfo.
|
|
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: Namespace
|
|
metadata:
|
|
name: podinfo
|
|
```
|
|
|
|
Then create a Kustomization to deploy podinfo.
|
|
```yaml
|
|
apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
|
|
kind: Kustomization
|
|
metadata:
|
|
name: podinfo
|
|
namespace: flux-system
|
|
spec:
|
|
interval: 5m
|
|
targetNamespace: podinfo
|
|
path: ./clusters/my-cluster/podinfo
|
|
prune: true
|
|
sourceRef:
|
|
kind: GitRepository
|
|
name: flux-system
|
|
healthChecks:
|
|
- apiVersion: apps/v1
|
|
kind: Deployment
|
|
name: podinfo
|
|
namespace: podinfo
|
|
timeout: 1m
|
|
```
|
|
|
|
## Creating the Git provider
|
|
|
|
Creating a git provider is similar to creating other providers.
|
|
The only difference is that with git providers `spec.address` needs to point to the same git repository that the event source originates from.
|
|
|
|
=== "GitHub"
|
|
```yaml
|
|
apiVersion: notification.toolkit.fluxcd.io/v1beta1
|
|
kind: Provider
|
|
metadata:
|
|
name: flux-system
|
|
namespace: flux-system
|
|
spec:
|
|
type: github
|
|
address: https://github.com/<username>/fleet-infra
|
|
secretRef:
|
|
name: git
|
|
```
|
|
|
|
=== "GitLab"
|
|
```yaml
|
|
apiVersion: notification.toolkit.fluxcd.io/v1beta1
|
|
kind: Provider
|
|
metadata:
|
|
name: flux-system
|
|
namespace: flux-system
|
|
spec:
|
|
type: gitlab
|
|
address: https://gitlab.com/<username>/fleet-infra
|
|
secretRef:
|
|
name: git
|
|
```
|
|
=== "Bitbucket"
|
|
```bash
|
|
```
|
|
=== "Azure DevOps"
|
|
```bash
|
|
```
|
|
|
|
## Creating the alert
|
|
|
|
=== "GitHub"
|
|
```bash
|
|
$ flux create alert podinfo \
|
|
--provider-ref git \
|
|
--event-severity info \
|
|
--event-source 'Kustomization/podinfo' \
|
|
--namespace 'flux-system' \
|
|
--export
|
|
---
|
|
apiVersion: notification.toolkit.fluxcd.io/v1beta1
|
|
kind: Alert
|
|
metadata:
|
|
name: podinfo
|
|
namespace: flux-system
|
|
spec:
|
|
providerRef:
|
|
name: flux-system
|
|
eventSeverity: info
|
|
eventSources:
|
|
- kind: Kustomization
|
|
name: podinfo
|
|
namespace: flux-system
|
|
```
|
|
=== "GitLab"
|
|
```bash
|
|
```
|
|
=== "Bitbucket"
|
|
```bash
|
|
```
|
|
=== "Azure DevOps"
|
|
```bash
|
|
```
|
|
|
|
|
|
By now the fleet-infra repository should have a similar directory structure.
|
|
```
|
|
fleet-infra
|
|
└── clusters/
|
|
└── my-cluster/
|
|
├── flux-system/
|
|
│ ├── gotk-components.yaml
|
|
│ ├── gotk-sync.yaml
|
|
│ └── kustomization.yaml
|
|
├── podinfo/
|
|
│ ├── namespace.yaml
|
|
│ ├── deployment.yaml
|
|
│ ├── hpa.yaml
|
|
│ ├── service.yaml
|
|
│ └── kustomization.yaml
|
|
├── podinfo-kustomization.yaml
|
|
└── podinfo-notification.yaml
|
|
```
|
|
|
|
If podinfo is deployed and the health checks pass you should get a successful status in
|
|
your forked podinfo repository.
|
|
|
|
If everything is setup correctly there should now be a green check-mark next to the latest commit.
|
|
Clicking the check-mark should show a detailed view.
|
|
|
|
=== "Github"
|
|
|
|
=== "GitLab"
|
|
 |
|
|
|
|
## Generate an error
|
|
|
|
A deployment failure can be forced by setting an invalid image tag in the podinfo deployment.
|
|
```yaml
|
|
apiVersion: apps/v1
|
|
kind: Deployment
|
|
spec:
|
|
template:
|
|
spec:
|
|
containers:
|
|
- name: podinfod
|
|
image: ghcr.io/stefanprodan/podinfo:fake
|
|
```
|
|
|
|
After the commit has been reconciled it should return a failed commit status.
|
|
|
|
=== "GitHub"
|
|
|
|
=== "GitLab"
|
|
 |
|
|
|
|
|