From cb879ec669b6fe274f7918489f106bccc4f0de38 Mon Sep 17 00:00:00 2001 From: Christian Schlatter Date: Fri, 30 Jun 2023 13:46:46 +0200 Subject: [PATCH] recreate docs with mkdocs --- Readme.md | 41 +--------- doc/github/argocd.yml | 48 ----------- doc/github/helm.yml | 38 --------- doc/github/kustomize.yml | 38 --------- doc/gitlab/.gitlab-ci.yml | 65 --------------- doc/integrations.md | 29 ------- docs/build.md | 20 +++++ docs/examples.md | 106 +++++++++++++++++++++++++ {doc => docs}/img/github-argo-diff.png | Bin {doc => docs}/img/github-diff.png | Bin {doc => docs}/img/goff-argo-diff.png | Bin {doc => docs}/img/goff-diff.png | Bin docs/index.md | 71 +++++++++++++++++ docs/integrations.md | 83 +++++++++++++++++++ mkdocs.yml | 16 ++++ 15 files changed, 298 insertions(+), 257 deletions(-) delete mode 100644 doc/github/argocd.yml delete mode 100644 doc/github/helm.yml delete mode 100644 doc/github/kustomize.yml delete mode 100644 doc/gitlab/.gitlab-ci.yml delete mode 100644 doc/integrations.md create mode 100644 docs/build.md create mode 100644 docs/examples.md rename {doc => docs}/img/github-argo-diff.png (100%) rename {doc => docs}/img/github-diff.png (100%) rename {doc => docs}/img/goff-argo-diff.png (100%) rename {doc => docs}/img/goff-diff.png (100%) create mode 100644 docs/index.md create mode 100644 docs/integrations.md create mode 100644 mkdocs.yml diff --git a/Readme.md b/Readme.md index 5a4f426..4218fe8 100644 --- a/Readme.md +++ b/Readme.md @@ -28,22 +28,6 @@ goff diff "/tmp/source" "/tmp/target" --title=Preview --output-dir . ### ArgoCD Application -Example for ArgoCD Application diff -```bash -#Render all ArgoCD manifests in directory from source branch -goff argocd app "./source/argocd" --repo-server="repo-server:8081" --output-dir=/tmp/source/ -#Render all ArgoCD manifests in directory from target branch -goff argocd app "./target/argocd" --repo-server="repo-server:8081" --output-dir=/tmp/target/ -#Diff rendered Kubernetes manifests -goff diff "/tmp/source" "/tmp/target" --output-dir . -``` - -1. Create a new branch and commit your changes in your ArgoCd Application - ![GitHub Diff](doc/img/github-argo-diff.png) -2. Run your pipeline, Goff renders the Appication into manifests calculate the diff between the source and target branch. -3. Check the auto generated comment in your Pull request and review the changes - ![GitHub Diff](doc/img/goff-argo-diff.png) - ## Usage ```bash @@ -77,27 +61,6 @@ Use "goff [command] --help" for more information about a command. | ArgoCD Application | ✅ Needs a local ArgoCD Repo server instance | | ArgoCD ApplicationSet | 🚧 Not yet fully supported (List generators only) | -## Build - -### Build binary from source - -```bash -go build -o goff goff -``` - -### Build Image with dagger - -```bash -export REGISTRY_PASSWORD=.... -export REGISTRY_USER=.... -go run ci/main.go -``` - -If you wanna try the new fancy Dagger TUI +## Documentation -```bash -export _EXPERIMENTAL_DAGGER_TUI=1 -export REGISTRY_PASSWORD=.... -export REGISTRY_USER=.... -dagger run go run ci/main.go -``` +here diff --git a/doc/github/argocd.yml b/doc/github/argocd.yml deleted file mode 100644 index 88a0ab5..0000000 --- a/doc/github/argocd.yml +++ /dev/null @@ -1,48 +0,0 @@ -on: - pull_request: - types: [opened, synchronize] - paths: - - "argocd/**" - -permissions: - contents: read - pull-requests: write - -name: Diff GitOps Environments - -jobs: - diff-env-argo: - # The type of runner that the job will run on - runs-on: ubuntu-latest - services: - reposerver: - image: quay.io/puzzle/argocd-repo-server:latest - ports: - - "8081:8081" - options: >- - --health-cmd "nc -z localhost 8081" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - container: - image: quay.io/puzzle/goff:latest - steps: - - name: Checkout PR - uses: actions/checkout@v3 - with: - path: source - - name: Checkout Target of PR - uses: actions/checkout@v3 - with: - path: target - ref: ${{ github.event.pull_request.base.ref }} - - run: | - goff argocd "./source/argocd" --repo-server="reposerver:8081" --output-dir=/tmp/source/ - goff argocd "./target/argocd" --repo-server="reposerver:8081" --output-dir=/tmp/target/ - goff diff "/tmp/source" "/tmp/target" --output-dir . - - name: comment PR - uses: machine-learning-apps/pr-comment@master - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - path: diff.md \ No newline at end of file diff --git a/doc/github/helm.yml b/doc/github/helm.yml deleted file mode 100644 index cd9d16e..0000000 --- a/doc/github/helm.yml +++ /dev/null @@ -1,38 +0,0 @@ -on: - pull_request: - types: [opened, synchronize] - paths: - - "helm/**" - -permissions: - contents: read - pull-requests: write - -name: Diff GitOps Environments - -jobs: - diff-env-helm: - # The type of runner that the job will run on - runs-on: ubuntu-latest - container: - image: quay.io/puzzle/goff:latest - steps: - - name: Checkout PR - uses: actions/checkout@v3 - with: - path: source - - name: Checkout Target of PR - uses: actions/checkout@v3 - with: - path: target - ref: ${{ github.event.pull_request.base.ref }} - - run: | - helm template mychart ./source/helm/mychart --output-dir /tmp/source/out - helm template mychart ./target/helm/mychart --output-dir /tmp/target/out - goff diff "/tmp/source" "/tmp/target" --output-dir . - - name: comment PR - uses: machine-learning-apps/pr-comment@master - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - path: diff.md \ No newline at end of file diff --git a/doc/github/kustomize.yml b/doc/github/kustomize.yml deleted file mode 100644 index eb60458..0000000 --- a/doc/github/kustomize.yml +++ /dev/null @@ -1,38 +0,0 @@ -on: - pull_request: - types: [opened, synchronize] - paths: - - "kustomize/**" - -permissions: - contents: read - pull-requests: write - -name: Diff GitOps Environments - -jobs: - diff-env-kustomize: - # The type of runner that the job will run on - runs-on: ubuntu-latest - container: - image: quay.io/puzzle/goff:latest - steps: - - name: Checkout PR - uses: actions/checkout@v3 - with: - path: source - - name: Checkout Target of PR - uses: actions/checkout@v3 - with: - path: target - ref: ${{ github.event.pull_request.base.ref }} - - run: | - goff kustomize build ./source/kustomize --output-dir /tmp/source/out - goff kustomize build ./target/kustomize --output-dir /tmp/target/out - goff diff "/tmp/source" "/tmp/target" --title=Preview --output-dir . - - name: comment PR - uses: machine-learning-apps/pr-comment@master - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - path: diff.md \ No newline at end of file diff --git a/doc/gitlab/.gitlab-ci.yml b/doc/gitlab/.gitlab-ci.yml deleted file mode 100644 index f0a0c5e..0000000 --- a/doc/gitlab/.gitlab-ci.yml +++ /dev/null @@ -1,65 +0,0 @@ -stages: # List of stages for jobs, and their order of execution - - merge - -create_comment_helm: - stage: merge - image: quay.io/puzzle/goff:latest - script: - - echo "Target branch $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" - - git clone -b $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --single-branch $CI_REPOSITORY_URL /tmp/checkout/target - - mkdir -p /tmp/source - - mkdir -p /tmp/target - - helm template mychart ./helm/mychart --output-dir /tmp/source/out - - helm template mychart /tmp/checkout/target/helm/mychart --output-dir /tmp/target/out - - goff diff "/tmp/source" "/tmp/target" --output-dir /tmp/ - - glab auth login --hostname gitlab.puzzle.ch -t $GITLAB_ACCESS_TOKEN - - glab mr note -m "$(cat /tmp/diff.md)" $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME - rules: - - if: $CI_PIPELINE_SOURCE == 'merge_request_event' - changes: - - helm/**/* - -create_comment_kustomize: - stage: merge - image: quay.io/puzzle/goff:latest - script: - - echo summy - - echo "Target branch $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" - - git clone -b $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --single-branch $CI_REPOSITORY_URL /tmp/checkout/target - - mkdir -p /tmp/source - - mkdir -p /tmp/target - - cd kustomize - - goff kustomize build . --output-dir=/tmp/out/source - - cd /tmp/checkout/target/kustomize - - goff kustomize build . --output-dir=/tmp/out/target - - goff diff "/tmp/out/source" "/tmp/out/target" --output-dir /tmp/ - - glab auth login --hostname gitlab.puzzle.ch -t $GITLAB_ACCESS_TOKEN - - glab mr note -m "$(cat /tmp/diff.md)" $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME - rules: - - if: $CI_PIPELINE_SOURCE == 'merge_request_event' - changes: - - kustomize/**/* - - -create_comment_argo: - services: - - name: quay.io/argoproj/argocd:latest - alias: repo-server - entrypoint: - - "/usr/local/bin/argocd-repo-server" - stage: merge - image: quay.io/puzzle/goff:latest - script: - - echo "Target branch $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" - - git clone -b $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --single-branch $CI_REPOSITORY_URL /tmp/checkout/target - - mkdir -p /tmp/source - - mkdir -p /tmp/target - - goff argocd "./argocd" --repo-server="repo-server:8081" --output-dir=/tmp/source/ - - goff argocd "/tmp/checkout/target/argocd" --output-dir=/tmp/target/ - - goff diff "/tmp/source" "/tmp/target" --output-dir /tmp/ - - glab auth login --hostname gitlab.puzzle.ch -t $GITLAB_ACCESS_TOKEN - - glab mr note -m "$(cat /tmp/diff.md)" $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME - rules: - - if: $CI_PIPELINE_SOURCE == 'merge_request_event' - changes: - - argocd/**/* diff --git a/doc/integrations.md b/doc/integrations.md deleted file mode 100644 index ad54b90..0000000 --- a/doc/integrations.md +++ /dev/null @@ -1,29 +0,0 @@ -Integrations -=== - -We provide and support following CI Tools - -# Github - -//TODO - -## ArgoCD Applications Considerations - -Due the limitation of Github we can not override the entrypoint of a service image. -Therefore we recommend to use our argo-cd-repo server image which just overrides the entrypoint and install netcat -for the health probe. - -# Gitlab - -//TODO - -## OpenShift Considerations - -If you are using Gitlab Runners on OpenShift, yu have to tweak your runner configurations to run the ArgoCD Repo Server as service. - -```toml - [runners.kubernetes] - [[runners.kubernetes.volumes.empty_dir]] - name = "argo-repo-gpg" - mount_path = "/app/config/gpg/keys" -``` \ No newline at end of file diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..cf53012 --- /dev/null +++ b/docs/build.md @@ -0,0 +1,20 @@ +# Build + +### Build binary from source + +```bash +go build -o goff goff +``` + +### Build Image with dagger + +```bash +go run ci/main.go +``` + +or + +```bash +dagger run go run ci/main.go +``` + diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..8f278e7 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,106 @@ +# Examples + + +## Helm + +```bash +#Clone source branch +git clone --branch feature/A git@github.com:schlapzz/goff-github.git ./source/ + +#Clone target branch +git clone --branch main git@github.com:schlapzz/goff-github.git ./target/ + +#Render source chart +helm template mychart ./source/helm/mychart --output-dir /tmp/source/out +#Render target Chart +helm template mychart ./target/helm/mychart --output-dir /tmp/target/out + +#Diff rendered manifests +goff diff "/tmp/source" "/tmp/target" --output-dir . +``` + +## Kustomize + +Example for Kustomization diff +```bash +#Clone source branch +git clone --branch feature/A git@github.com:schlapzz/goff-github.git ./source/ + +#Clone target branch +git clone --branch main git@github.com:schlapzz/goff-github.git ./target/ + +#Build base and all overlays from source branch +goff kustomize build ./source/kustomize --output-dir /tmp/source/out +#Build base and all overlays from target branch +goff kustomize build ./target/kustomize --output-dir /tmp/target/out + +#Diff rendered manifests +goff diff "/tmp/source" "/tmp/target" --title=Preview --output-dir . +``` + +## ArgoCD + + +```bash +goff argocd -h +Render manifests from ArgoCD resources + +Usage: + goff argocd [flags] + goff argocd [command] + +Available Commands: + app Render manifests from ArgoCD Application + appset Render ArgoCD Applications manifests from ApplicationSets + +Flags: + -h, --help help for argocd + -o, --output-dir string Output directory (default ".") + -p, --password string Repo password + -i, --ssh-key string Repo SSH Key + -u, --username string Repo username + +Global Flags: + -l, --log-level string Set loglevel [debug, info, error] (default "error") + +Use "goff argocd [command] --help" for more information about a command. +``` +### ArgoCD Application +Example for ArgoCD Application diff +```bash +#Clone source branch +git clone --branch feature/A git@github.com:schlapzz/goff-github.git ./source/ + +#Clone target branch +git clone --branch main git@github.com:schlapzz/goff-github.git ./target/ + +#Start ArgoCD repo server to render Applications +docker run -d -p 8081:8081 quay.io/argoproj/argocd:latest + +#Render all ArgoCD manifests in directory from source branch +goff argocd app "./source/argocd/app" --repo-server="localhost:8081" --output-dir=/tmp/source/ +#Render all ArgoCD manifests in directory from target branch +goff argocd app "./target/argocd/app" --repo-server="localhost:8081" --output-dir=/tmp/target/ +#Diff rendered Kubernetes manifests +goff diff "/tmp/source" "/tmp/target" --output-dir . +``` + + +### ArgoCD ApplicationSet + +Example for ArgoCD ApplicationSet diff +```bash +#Clone source branch +git clone --branch feature/A git@github.com:schlapzz/goff-github.git ./source/ + +#Clone target branch +git clone --branch main git@github.com:schlapzz/goff-github.git ./target/ + +#Render all ArgoCD manifests in directory from source branch +goff argocd appset "./source/argocd/app-set" --repo-server="localhost:8081" --output-dir=/tmp/source/ +#Render all ArgoCD manifests in directory from target branch +goff argocd appset "./target/argocd/app-set" --repo-server="localhost:8081" --output-dir=/tmp/target/ +#Diff rendered Kubernetes manifests +goff diff "/tmp/source" "/tmp/target" --output-dir . +``` + diff --git a/doc/img/github-argo-diff.png b/docs/img/github-argo-diff.png similarity index 100% rename from doc/img/github-argo-diff.png rename to docs/img/github-argo-diff.png diff --git a/doc/img/github-diff.png b/docs/img/github-diff.png similarity index 100% rename from doc/img/github-diff.png rename to docs/img/github-diff.png diff --git a/doc/img/goff-argo-diff.png b/docs/img/goff-argo-diff.png similarity index 100% rename from doc/img/goff-argo-diff.png rename to docs/img/goff-argo-diff.png diff --git a/doc/img/goff-diff.png b/docs/img/goff-diff.png similarity index 100% rename from doc/img/goff-diff.png rename to docs/img/goff-diff.png diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2081022 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,71 @@ +[![ci](https://github.com/puzzle/goff/actions/workflows/main.yml/badge.svg)](https://github.com/puzzle/goff/actions/workflows/main.yml) + +# GOFF #{{ goff.version }} + +Inspired from Kostis Kapelonis (Codefresh.io) talk at the KubeCon about [How to Preview and Diff Your Argo CD Deployments](https://youtu.be/X392bJX0AEs) we relased our own GitOps Diff tool (Goff). This tool helps you to preview your changes in your GitOps Repository. + +## How it works + + +Example for ArgoCD Application diff +```bash +#Render all ArgoCD manifests in directory from source branch +goff argocd app "./source/argocd" --repo-server="repo-server:8081" --output-dir=/tmp/source/ +#Render all ArgoCD manifests in directory from target branch +goff argocd app "./target/argocd" --repo-server="repo-server:8081" --output-dir=/tmp/target/ +#Diff rendered Kubernetes manifests +goff diff "/tmp/source" "/tmp/target" --output-dir . +``` + +1. Setup your pipeline in your GitOps repository. You can find examples integrations [for Github, Gitlab and Gitea here](integrations.md) +2. Create a new branch and commit your changes in your ArgoCd Application + ![GitHub Diff](img/github-argo-diff.png) +3. Run your pipeline, Goff renders the Appication into manifests calculate the diff between the source and target branch. +4. Check the auto generated comment in your Pull request and review the changes + ![GitHub Diff](img/goff-argo-diff.png) + +## Installation + +You can download the latest release here +Or you can use the pre built Docker image `docker pull quay.io/puzzle/goff:#{{ goff.version }}` + +The image includes following tools: + +* goff #{{ goff.version }} +* Gitlab CLI +* Gitea CLI +* Helm +* Git + +## Usage + +```bash +GitOps Diff Tool + +Usage: + goff [command] + +Available Commands: + argocd Render manifests from ArgoCD resources + completion Generate the autocompletion script for the specified shell + diff Diff files [sourceDir] [targetDir] + help Help about any command + kustomize Generate a DOT file to visualize the dependencies between your kustomize components + split Split manifests [manifestFile] + +Flags: + -h, --help help for goff + -l, --logLevel string Set loglevel [debug, info, error] (default "error") + +Use "goff [command] --help" for more information about a command. +``` + +## Supported Tools + +| Tooling | Support | +|-----------------------|----------------------------------------------| +| Plain manifests | ✅ | +| Helm | ✅ Supported through plain manifests | +| Kustomize | ✅ | +| ArgoCD Application | ✅ Needs a local ArgoCD Repo server instance | +| ArgoCD ApplicationSet | 🚧 Not yet fully supported (List generators only) | diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 0000000..461e87b --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,83 @@ +# Integrations + +## Github + +```yaml +on: + pull_request: + types: [opened, synchronize] + paths: + - "argocd/**" + +permissions: + contents: read + pull-requests: write + +name: Diff GitOps Environments + +jobs: + diff-env-argo: + # The type of runner that the job will run on + runs-on: ubuntu-latest + services: + reposerver: + image: quay.io/puzzle/argocd-repo-server:latest + ports: + - "8081:8081" + options: >- + --health-cmd "nc -z localhost 8081" + --health-interval 10s + --health-timeout 5s + --health-retries 5 + container: + image: quay.io/puzzle/goff:latest + steps: + - name: Checkout PR + uses: actions/checkout@v3 + with: + path: source + - name: Checkout Target of PR + uses: actions/checkout@v3 + with: + path: target + ref: ${{ github.event.pull_request.base.ref }} + - run: | + goff argocd app "./source/argocd" --repo-server="reposerver:8081" --output-dir=/tmp/source/ + goff argocd app "./target/argocd" --repo-server="reposerver:8081" --output-dir=/tmp/target/ + goff diff "/tmp/source" "/tmp/target" --output-dir . + - name: comment PR + uses: machine-learning-apps/pr-comment@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + path: diff.md +``` + +## Gitlab + +```yaml +stages: + - merge + +create_comment: + stage: merge + image: quay.io/puzzle/goff:latest + script: + - echo "Target branch $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" + - git clone -b $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --single-branch $CI_REPOSITORY_URL /tmp/checkout/target + - mkdir -p /tmp/source + - mkdir -p /tmp/target + - cd kustomize + - goff kustomize build . --output-dir=/tmp/out/source + - cd /tmp/checkout/target/kustomize + - goff kustomize build . --output-dir=/tmp/out/target + - goff diff "/tmp/out/source" "/tmp/out/target" --output-dir /tmp/ + - glab auth login --hostname gitlab.puzzle.ch -t $GITLAB_ACCESS_TOKEN + - glab mr note -m "$(cat /tmp/diff.md)" $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + changes: + - kustomize/**/* +``` + +## Gitea \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e2b1de4 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,16 @@ +site_name: GOFF +site_url: https://example.com/ +nav: + - Home: index.md + - Examples: examples.md + - Integrations: integrations.md + - Build: build.md +theme: readthedocs +plugins: + - search + - markdownextradata: + jinja_options: + variable_start_string: "#{{" +extra: + goff: + version: !ENV [GOFF_VERSION, 'v0.0.0'] \ No newline at end of file