Skip to content

Commit

Permalink
docs: update gitops env var docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@adityathebe
adityathebe committed Jun 25, 2024
1 parent d260a2a commit 97d53c7
Showing 1 changed file with 201 additions and 61 deletions.
262 changes: 201 additions & 61 deletions mission-control/docs/playbooks/Actions/gitops.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,81 +1,92 @@
---
title: GitOps
---
import Templating from "../../reference/playbooks/context.mdx"

import Templating from '../../reference/playbooks/context.mdx'

# <Icon name="git"/> GitOps Action

GitOps action allows you to make commits and push to a remote repository.

```yaml title="update-pod-namespace.yaml"
```yaml title="edit-kubernetes-manifests-gitops.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: edit-kubernetes-manifests-gitops
spec:
title: 'Edit Kustomize Resource'
icon: flux
icon: 'flux'
parameters:
- default: 'chore: update $(.config.type)/$(.config.name)'
label: Commit Message
name: commit_message
- default: $(.config.config | toJSON | neat | json | toYAML)
label: ""
name: yamlInput
label: 'Commit Message'
name: 'commit_message'
- default: '$(.config.config | toJSON | neat | json | toYAML)'
label: 'Changes'
name: 'yamlInput'
properties:
size: large
type: code

size: 'large'
type: 'code'
configs:
- labelSelector: 'kustomize.toolkit.fluxcd.io/name'

env:
- name: file_path
value: {{ .config.config | jq `.metadata.annotations["config.kubernetes.io/origin"]` | yaml).path }}
- name: kustomization_path
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization").Config | json | jq `.spec.path` }}
- name: git_url
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization/Kubernetes::GitRepository").Config | json | jq `.spec.url` }}
- name: git_branch
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization/Kubernetes::GitRepository").Config | json | jq `.spec.ref.branch` }}

actions:
- name: Create Pull Request With Changes
- name: 'Create Pull Request With Changes'
gitops:
repo:
url: '$(.env.git_url)'
connection:
base: '$(.env.git_branch)'
branch: edit-manifest-$(random.Alpha 8)
url: 'https://github.com/flanksource/flux'
connection: 'connection://default/github'
base: 'main'
branch: 'edit-manifest-$(random.Alpha 8)'
commit:
author: '$(.user.name)'
email: '$(.user.email)'
message: $(.params.commit_message)
message: '$(.params.commit_message)'
pr:
title: $(.params.commit_message)
title: '$(.params.commit_message)'
patches:
- path: '$(filepath.Join .env.kustomization_path .env.file_path)'
- path: 'prod/kustomization.yaml'
yq: |
select(
.kind=="$(.config.config | jq `.kind`)" and
.metadata.name=="$(.config.config | jq `.metadata.name`)"
) |= $(.params.yamlInput | yaml | toJSON)
```
<Action anyOf={['patches', 'files']} rows={[
{field: "repo", description: "The repository details", scheme: "[Repository](#repository)", required: true},
{field: "commit", description: "Commit details", scheme: "[Commit](#commit-detail)", required: true},
{field: "pr", description: "Create a Pull Request instead of a commit (Only available for `github` and `gitlab`)", scheme: "[PullRequest](#pull-request)"},
{field: "patches", description: "List of JQ/YQ patches to apply", scheme: "[[]Patch](#patch)"},
{field: "files", description: "List of files to create", scheme: "[[]File](#file)"}
]}/>

<Action
anyOf={['patches', 'files']}
rows={[
{
field: 'repo',
description: 'The repository details',
scheme: '[Repository](#repository)',
required: true
},
{
field: 'commit',
description: 'Commit details',
scheme: '[Commit](#commit-detail)',
required: true
},
{
field: 'pr',
description:
'Create a Pull Request instead of a commit (Only available for `github` and `gitlab`)',
scheme: '[PullRequest](#pull-request)'
},
{
field: 'patches',
description: 'List of JQ/YQ patches to apply',
scheme: '[[]Patch](#patch)'
},
{
field: 'files',
description: 'List of files to create',
scheme: '[[]File](#file)'
}
]}
/>

### Repository


<Fields oneOf={["connection", "url"]} rows={[
{field: "connection", description: "Connection name to use the credentials for the git repo", scheme: "string"},
{field: "url", description: "URL of the git repository", scheme: "string"},
Expand All @@ -85,7 +96,6 @@ spec:

]}/>


### Commit Detail

| Field | Description | Scheme | Required | Templatable |
Expand Down Expand Up @@ -120,30 +130,53 @@ Files create or delete existing files on the git repo.
| `path` | Path to file | `string` | `true` | `true` |
| `content` | Content of the file. Use the `$delete` keyword to delete an existing file | `string` | `true` | `true` |

## Env Vars

GitOps action receives a set of commonly used [env vars](../../reference/playbooks/env-vars). These env vars are extracted by traversing up the Flux Kustomization & Git Repository that created the config resource the playbook is running against.
They are

<Fields rows={[
{field: "git.file", description: `Name of the file that created the config resource the playbook is run against.`, scheme: "string"},
{field: "git.url", description: "URL of the git repository", scheme: "string"},
{field: "git.branch", description: "The primary branch", scheme: "string"},
{field: "kustomize.path", description: "Path of the kustomization file that created the config resource the playbook is run against. This comes from the spec of the kustomization.", scheme: "string"},
]}/>

<details summary="Origin Annotation">

In order for `git.file` to work, the `config.kubernetes.io/origin` annotation must be present in the config resource. You can set `buildMetadata: [originAnnotations]` in the kustomization file and the kustomization will
add the annotation with the correct path.
## Custom Origin Annotation

In the example above, you saw a playbook that edited Flux-created manifests. However, there was a slight issue - it had some variables hardcoded, specifically the git repository, git branch, and the kustomization file path. When you have configurations from multiple clusters, you'll need to duplicate the playbook for each cluster, as the git repository and kustomization file path will differ. Even if you have multiple Flux kustomizations on a single cluster, you'll need to duplicate the playbook for each of those kustomizations.

There's a better way to build a single generic GitOps playbook that works for configurations with any Flux source and kustomization.

When a GitOps action is run against a config resource that has a `config.kubernetes.io/origin` annotation, the following [env vars](../../reference/playbooks/env-vars) are automatically available:

<Fields
rows={[
{
field: 'git.file',
description: `Name of the file that created the config resource the playbook is run against.`,
scheme: 'string'
},
{
field: 'git.url',
description: 'URL of the git repository',
scheme: 'string'
},
{
field: 'git.branch',
description: 'The primary branch',
scheme: 'string'
},
{
field: 'kustomize.path',
description:
'Path of the kustomization file that created the config resource the playbook is run against. This comes from the spec of the kustomization.',
scheme: 'string'
}
]}
/>

These env vars are extracted by traversing up the Flux Kustomization and Git Repository that created the config resource the playbook is running against. We'll see this in detail shortly.

To tag all the resources with that annotation, you'll need to add `originAnnotations` to the buildMetadata field as shown below:

<details summary="Setting origin annotation">

```yaml title='kustomization.yaml'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
// highlight-next-line
buildMetadata: [originAnnotations]
resources:
- monitoring
- monitoring
```

The above kustomization would add the following annotation to the config resource:
Expand All @@ -157,9 +190,116 @@ metadata:
path: monitoring/alertmanager.yaml
...
```

</details>

## Templating
### Example

<Tabs>
<TabItem label="Wihout origin annotation" value="without-origin-annotation">

```yaml title="edit-kubernetes-manifests-gitops.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: edit-kubernetes-manifests-gitops
spec:
title: 'Edit Kustomize Resource'
icon: flux
parameters:
- default: 'chore: update $(.config.type)/$(.config.name)'
label: Commit Message
name: commit_message
- default: $(.config.config | toJSON | neat | json | toYAML)
label: ""
name: yamlInput
properties:
size: large
type: code
configs:
- labelSelector: 'kustomize.toolkit.fluxcd.io/name'
env:
- name: file_path
value: {{ .config.config | jq `.metadata.annotations["config.kubernetes.io/origin"]` | yaml).path }}
- name: kustomization_path
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization").Config | json | jq `.spec.path` }}
- name: git_url
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization/Kubernetes::GitRepository").Config | json | jq `.spec.url` }}
- name: git_branch
value: {{ (catalog_traverse .config.id "Kubernetes::Kustomization/Kubernetes::GitRepository").Config | json | jq `.spec.ref.branch` }}
actions:
- name: Create Pull Request With Changes
gitops:
repo:
url: '$(.env.git_url)'
connection: 'connection://default/github'
base: '$(.env.git_branch)'
branch: edit-manifest-$(random.Alpha 8)
commit:
author: '$(.user.name)'
email: '$(.user.email)'
message: $(.params.commit_message)
pr:
title: $(.params.commit_message)
patches:
- path: '$(filepath.Join .env.kustomization_path .env.file_path)'
yq: |
select(
.kind=="$(.config.config | jq `.kind`)" and
.metadata.name=="$(.config.config | jq `.metadata.name`)"
) |= $(.params.yamlInput | yaml | toJSON)
```
</TabItem>
<TabItem label="With origin annotation" value="with-origin-annotation">
<Templating/>
```yaml title="edit-kubernetes-manifests-gitops.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: edit-kubernetes-manifests-gitops
spec:
title: 'Edit Kustomize Resource'
icon: flux
parameters:
- default: 'chore: update $(.config.type)/$(.config.name)'
label: Commit Message
name: commit_message
- default: $(.config.config | toJSON | neat | json | toYAML)
label: ""
name: yamlInput
properties:
size: large
type: code
configs:
- labelSelector: 'kustomize.toolkit.fluxcd.io/name'
actions:
- name: Create Pull Request With Changes
gitops:
repo:
url: '$(.env.git.url)'
connection: 'connection://default/github'
base: '$(.env.git.branch)'
branch: edit-manifest-$(random.Alpha 8)
commit:
author: '$(.user.name)'
email: '$(.user.email)'
message: $(.params.commit_message)
pr:
title: $(.params.commit_message)
patches:
- path: '$(filepath.Join .env.kustomization.path .env.git.file)'
yq: |
select(
.kind=="$(.config.config | jq `.kind`)" and
.metadata.name=="$(.config.config | jq `.metadata.name`)"
) |= $(.params.yamlInput | yaml | toJSON)
```
</TabItem>
</Tabs>
## Templating
<Templating />

0 comments on commit 97d53c7

Please sign in to comment.