documentation

3 years ago · 2ca94fed31
1 changed files with 566 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,566 @@
+# Antennas - GITOPS repository
+
+## Pre-requisites
+
+* Create the required namespaces.
+
+```sh
+oc new-project antennas-dev
+oc new-project antennas-test
+oc new-project antennas-prod
+```
+
+* Install the OpenShift GitOps operator.
+
+* Fix the ArgoCD ingress route in order to use the router default TLS certificate.
+
+```sh
+oc patch argocd openshift-gitops -n openshift-gitops -p '{"spec":{"server":{"insecure":true,"route":{"enabled": true,"tls":{"termination":"edge","insecureEdgeTerminationPolicy":"Redirect"}}}}}' --type=merge
+```
+
+* Get the Webhook URL of your OpenShift Gitops installation
+
+```sh
+oc get route -n openshift-gitops openshift-gitops-server -o jsonpath='https://{.spec.host}/api/webhook'
+```
+
+* Add a webhook to your GitHub/GitLab repo
+
+  * Payload URL: *url above*
+  * Content-Type: Application/json
+
+* Label the `antennas-prod` namespace with argocd annotations
+
+```sh
+oc label namespace antennas-prod argocd.argoproj.io/managed-by=openshift-gitops
+```
+
+* Create the `antennas-prod` application.
+
+```sh
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: antennas-prod
+  namespace: openshift-gitops
+spec:
+  destination:
+    name: ''
+    namespace: antennas-prod
+    server: 'https://kubernetes.default.svc'
+  source:
+    path: .
+    repoURL: 'https://gitlab.com/nmasse-itix/antennas-gitops.git'
+    targetRevision: HEAD
+    helm:
+      valueFiles:
+      - values-prod.yaml
+  project: default
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+## Gitlab version
+
+Install the Gitlab Runner operator.
+And because there is a bug in the v1.10.0, you will have to install a beta version manually.
+
+```yaml
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+  name: gitlab-runner-catalog
+  namespace: openshift-marketplace
+spec:
+  sourceType: grpc
+  image: registry.gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/gitlab-runner-operator-catalog-source:amd64-v0.0.1-53d8a4e6
+  displayName: GitLab Runner Operators
+  publisher: GitLab Community (Beta)
+---
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+  name: gitlab-runner-operator
+  namespace: openshift-operators
+spec:
+  channel: stable
+  name: gitlab-runner-operator
+  source: gitlab-runner-catalog
+  sourceNamespace: openshift-marketplace
+```
+
+Create a runner in the `antennas-dev` namespace.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: gitlab-runner-secret
+  namespace: antennas-dev
+type: Opaque
+stringData:
+  runner-registration-token: REPLACE_ME # your project runner secret
+---
+apiVersion: apps.gitlab.com/v1beta2
+kind: Runner
+metadata:
+  name: nmasse-itix
+  namespace: antennas-dev
+spec:
+  gitlabUrl: https://gitlab.com
+  token: gitlab-runner-secret
+  tags: openshift, test
+```
+
+Go to your [Gitlab profile](https://gitlab.com/-/profile/personal_access_tokens) and generate a Personal Access Token with the **read_repository** and **write_repository**.
+
+Go on [quay.io](https://quay.io/), click on your name, select **Account Settings** and generate an encrypted password.
+
+On Gitlab, go in your repository's **Settings** > **CI/CD**.
+
+Expand the **Variables** section.
+
+Add two variables:
+
+* `QUAY_USERNAME`: contains your Quay.io username
+* `QUAY_PASSWORD`: contains your Quay.io encrypted password
+* `GITLAB_ACCESS_TOKEN`: contains your GitLab Personal Access Token
+
+Do not forget to add the **Masked** flag to the `QUAY_PASSWORD` and `GITLAB_ACCESS_TOKEN` variables!
+
+Create two public repositories on quay.io
+
+* antennas-front
+* antennas-incident
+
+Give the gitlab runner the right to manage the test namespace.
+
+```sh
+oc adm policy add-role-to-user admin system:serviceaccount:antennas-dev:default -n antennas-test
+```
+
+Give the gitlab runner the right to execute containers with any user.
+
+```sh
+oc adm policy add-scc-to-user anyuid -z default -n antennas-dev
+```
+
+Use the following `.gitlab-ci.yaml` file.
+
+```yaml
+# This file is a template, and might need editing before it works on your project.
+# This is a sample GitLab CI/CD configuration file that should run without any modifications.
+# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
+# it uses echo commands to simulate the pipeline execution.
+#
+# A pipeline is composed of independent jobs that run scripts, grouped into stages.
+# Stages run in sequential order, but jobs within stages run in parallel.
+#
+# For more information, see: https://docs.gitlab.com/ee/ci/yaml/index.html#stages
+
+stages:
+  - build
+  - test
+  - deploy
+
+default:
+  tags:
+    - "openshift"
+
+#
+# HEADS UP ! You will need to change those variables to match the location of
+# your Quay.io repository and GitLab git repository.
+#
+variables:
+  ANTENNAS_FRONT_IMAGE: quay.io/nmasse_itix/antennas-front
+  ANTENNAS_GITOPS_REPOSITORY: gitlab.com/nmasse-itix/antennas-gitops.git
+
+#
+# Build the source code of antennas-front, using Maven.
+#
+maven-build:
+  stage: build
+  image: maven:3.8.6-jdk-11
+  variables:
+    # This will suppress any download for dependencies and plugins or upload messages which would clutter the console log.
+    # `showDateTime` will show the passed time in milliseconds. You need to specify `--batch-mode` to make this work.
+    MAVEN_OPTS: "-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=WARN -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true"
+    # As of Maven 3.3.0 instead of this you may define these options in `.mvn/maven.config` so the same config is used
+    # when running from the command line.
+    # `installAtEnd` and `deployAtEnd` are only effective with recent version of the corresponding plugins.
+    MAVEN_CLI_OPTS: "--batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true"
+  artifacts:
+    paths:
+      - target/
+  # Cache downloaded dependencies and plugins between builds.
+  # To keep cache across branches add 'key: "$CI_JOB_NAME"'
+  cache:
+    paths:
+      - .m2/repository
+  script:
+    - mvn $MAVEN_CLI_OPTS clean package
+
+#
+# Clone the Git repository containing all the YAML manifests needed to deploy
+# the complete application.
+#
+# Note that .git files do not fit very well with Gitlab CI artefact management,
+# so we pack and unpack the git repo before and after each usage.
+#
+clone-gitops:
+  stage: build
+  image: docker.io/alpine/git:2.36.3
+  artifacts:
+    paths:
+    - antennas-gitops.tgz
+  script:
+    - git clone https://ci:${GITLAB_ACCESS_TOKEN}@${ANTENNAS_GITOPS_REPOSITORY}
+    - tar -zcf antennas-gitops.tgz antennas-gitops
+
+#
+# Build the container image of antennas-front using buildah.
+#
+# Note: the digest of the newly built image is written in "antennas-front.iid".
+# this digest is then used to update the YAML files in the antennas-gitops
+# repository.
+#
+buildah:
+  stage: build
+  variables:
+    STORAGE_DRIVER: "vfs"
+    BUILDAH_FORMAT: "docker"
+  needs: [ "maven-build" ]
+  image: quay.io/buildah/stable:v1.27
+  artifacts:
+    paths:
+      - antennas-front.iid
+  script:
+    - buildah login -u "$QUAY_USERNAME" -p "$QUAY_PASSWORD" quay.io
+    - buildah build -f src/main/docker/Dockerfile.jvm -t ${ANTENNAS_FRONT_IMAGE}:latest .
+    - buildah push --tls-verify=false --digestfile antennas-front.iid ${ANTENNAS_FRONT_IMAGE}:latest
+
+#
+# Update the Helm values files to use the newly built image.
+#
+# Note: yq (https://mikefarah.gitbook.io/) is used to update values.yaml
+#
+helm-update:
+  stage: build
+  needs: [ "buildah", "clone-gitops" ]
+  image: docker.io/mikefarah/yq:4.28.2
+  artifacts:
+    paths:
+      - antennas-gitops.tgz
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+
+    # Get back the antennas-gitops repository from the Gitlab CI artifacts
+    tar -zxf antennas-gitops.tgz
+
+    # Update the Helm values files with the newly built image digest (and new name if not already done)
+    ANTENNAS_FRONT_IMAGE_DIGEST="$(cat antennas-front.iid)"
+    yq -i ".antennas-front.image.repository = \"${ANTENNAS_FRONT_IMAGE}\"" antennas-gitops/values-prod.yaml
+    yq -i ".antennas-front.image.repository = \"${ANTENNAS_FRONT_IMAGE}\"" antennas-gitops/values-test.yaml
+    yq -i ".antennas-front.image.digest = \"${ANTENNAS_FRONT_IMAGE_DIGEST}\"" antennas-gitops/values-prod.yaml
+    yq -i ".antennas-front.image.digest = \"${ANTENNAS_FRONT_IMAGE_DIGEST}\"" antennas-gitops/values-test.yaml
+
+    # Re-archive the antennas-gitops repository
+    rm -f antennas-gitops.tgz
+    tar -zcf antennas-gitops.tgz antennas-gitops
+
+#
+# Deploy the application in a test environment and wait for the deployment
+# to complete.
+#
+deploy-test:
+  stage: test
+  needs: [ "helm-update" ]
+  environment: test
+  image: quay.io/openshift/origin-cli:4.11
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+    tar -zxf antennas-gitops.tgz
+
+    # Download and install Helm
+    curl -sf https://get.helm.sh/helm-v3.10.1-linux-amd64.tar.gz | tar -zx --strip-components 1 -C /usr/local/bin linux-amd64/helm
+
+    # Generate the YAML manifests for the test environment
+    helm dependency build antennas-gitops
+    helm template antennas antennas-gitops --values antennas-gitops/values-test.yaml > test-manifests.yaml
+
+    # Apply the YAML manifests
+    oc apply -n antennas-test -f test-manifests.yaml
+
+    # Wait for the deployment to complete
+    oc rollout status deploy/antennas-front -n antennas-test --timeout=5m
+
+#
+# Run some integration tests in the test environment.
+#
+integration-test:
+  stage: test
+  needs: [ "deploy-test" ]
+  image: registry.access.redhat.com/ubi8/ubi:8.6
+  script:
+    - echo "Running integration tests..."
+    - curl -vf http://antennas-front.antennas-test.svc:8080/rest/incidents
+
+#
+# Commit the changes in the antennas-gitops repository so that ArgoCD can pick
+# them up.
+#
+deploy-prod:
+  stage: deploy
+  needs: [ "helm-update", "integration-test" ]
+  environment: production
+  image: docker.io/alpine/git:2.36.3
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+
+    # Inject git credentials
+    echo "https://ci:${GITLAB_ACCESS_TOKEN}@${ANTENNAS_GITOPS_REPOSITORY}" > ~/.git-credentials
+    chmod 600 ~/.git-credentials
+
+    tar -zxf antennas-gitops.tgz
+    chown $(id -u):$(id -g) -R antennas-gitops
+    cd antennas-gitops
+
+    # Commit the changes to the antennas-gitops repository
+    git config user.email "nmasse@redhat.com"
+    git config user.name "Gitlab-CI Bot"
+    git add values-prod.yaml
+    git commit -m 'update production image digest'    
+    git push
+```
+
+### Blue-green version
+
+An updated chart is available in the `blue-green` branch of this repo.
+
+And you can use the following `.gitlab-ci.yaml` file.
+
+```yaml
+# This file is a template, and might need editing before it works on your project.
+# This is a sample GitLab CI/CD configuration file that should run without any modifications.
+# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
+# it uses echo commands to simulate the pipeline execution.
+#
+# A pipeline is composed of independent jobs that run scripts, grouped into stages.
+# Stages run in sequential order, but jobs within stages run in parallel.
+#
+# For more information, see: https://docs.gitlab.com/ee/ci/yaml/index.html#stages
+
+stages:
+  - build
+  - test
+  - deploy
+
+default:
+  tags:
+    - "openshift"
+
+#
+# HEADS UP ! You will need to change those variables to match the location of
+# your Quay.io repository and GitLab git repository.
+#
+variables:
+  ANTENNAS_FRONT_IMAGE: quay.io/nmasse_itix/antennas-front
+  ANTENNAS_GITOPS_REPOSITORY: gitlab.com/nmasse-itix/antennas-gitops.git
+
+#
+# Build the source code of antennas-front, using Maven.
+#
+maven-build:
+  stage: build
+  image: maven:3.8.6-jdk-11
+  variables:
+    # This will suppress any download for dependencies and plugins or upload messages which would clutter the console log.
+    # `showDateTime` will show the passed time in milliseconds. You need to specify `--batch-mode` to make this work.
+    MAVEN_OPTS: "-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=WARN -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true"
+    # As of Maven 3.3.0 instead of this you may define these options in `.mvn/maven.config` so the same config is used
+    # when running from the command line.
+    # `installAtEnd` and `deployAtEnd` are only effective with recent version of the corresponding plugins.
+    MAVEN_CLI_OPTS: "--batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true"
+  artifacts:
+    paths:
+      - target/
+  # Cache downloaded dependencies and plugins between builds.
+  # To keep cache across branches add 'key: "$CI_JOB_NAME"'
+  cache:
+    paths:
+      - .m2/repository
+  script:
+    - mvn $MAVEN_CLI_OPTS clean package
+
+#
+# Clone the Git repository containing all the YAML manifests needed to deploy
+# the complete application.
+#
+# Note that .git files do not fit very well with Gitlab CI artefact management,
+# so we pack and unpack the git repo before and after each usage.
+#
+clone-gitops:
+  stage: build
+  image: docker.io/alpine/git:2.36.3
+  artifacts:
+    paths:
+    - antennas-gitops.tgz
+  script:
+    - git clone https://ci:${GITLAB_ACCESS_TOKEN}@${ANTENNAS_GITOPS_REPOSITORY}
+    - tar -zcf antennas-gitops.tgz antennas-gitops
+
+#
+# Build the container image of antennas-front using buildah.
+#
+# Note: the digest of the newly built image is written in "antennas-front.iid".
+# this digest is then used to update the YAML files in the antennas-gitops
+# repository.
+#
+buildah:
+  stage: build
+  variables:
+    STORAGE_DRIVER: "vfs"
+    BUILDAH_FORMAT: "docker"
+  needs: [ "maven-build" ]
+  image: quay.io/buildah/stable:v1.27
+  artifacts:
+    paths:
+      - antennas-front.iid
+  script:
+    - buildah login -u "$QUAY_USERNAME" -p "$QUAY_PASSWORD" quay.io
+    - buildah build -f src/main/docker/Dockerfile.jvm -t ${ANTENNAS_FRONT_IMAGE}:latest .
+    - buildah push --tls-verify=false --digestfile antennas-front.iid ${ANTENNAS_FRONT_IMAGE}:latest
+
+#
+# Update the Helm values files to use the newly built image.
+#
+# Note: yq (https://mikefarah.gitbook.io/) is used to update values.yaml
+#
+helm-update:
+  stage: build
+  needs: [ "buildah", "clone-gitops" ]
+  image: docker.io/mikefarah/yq:4.28.2
+  artifacts:
+    paths:
+      - antennas-gitops.tgz
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+
+    # Get back the antennas-gitops repository from the Gitlab CI artifacts
+    tar -zxf antennas-gitops.tgz
+
+    # Find the current target (green or blue?)
+    CURRENT_TARGET_PROD="$(yq .route.target antennas-gitops/values-prod.yaml)"
+    CURRENT_TARGET_TEST="$(yq .route.target antennas-gitops/values-test.yaml)"
+
+    # Pick the opposite target (prod)
+    case "$CURRENT_TARGET_PROD" in
+    blue)
+      TARGET_PROD=green
+      ;;
+    green)
+      TARGET_PROD=blue
+      ;;
+    *)
+      echo "Error: unexpected value"
+      ;;
+    esac
+
+    # Pick the opposite target (test)
+    case "$CURRENT_TARGET_TEST" in
+    blue)
+      TARGET_TEST=green
+      ;;
+    green)
+      TARGET_TEST=blue
+      ;;
+    *)
+      echo "Error: unexpected value"
+      ;;
+    esac
+
+    # Update the Helm values files with the newly built image digest (and new name if not already done)
+    ANTENNAS_FRONT_IMAGE_DIGEST="$(cat antennas-front.iid)"
+    yq -i ".antennas-front-${TARGET_PROD}.image.repository = \"${ANTENNAS_FRONT_IMAGE}\"" antennas-gitops/values-prod.yaml
+    yq -i ".antennas-front-${TARGET_TEST}.image.repository = \"${ANTENNAS_FRONT_IMAGE}\"" antennas-gitops/values-test.yaml
+    yq -i ".antennas-front-${TARGET_PROD}.image.digest = \"${ANTENNAS_FRONT_IMAGE_DIGEST}\"" antennas-gitops/values-prod.yaml
+    yq -i ".antennas-front-${TARGET_TEST}.image.digest = \"${ANTENNAS_FRONT_IMAGE_DIGEST}\"" antennas-gitops/values-test.yaml
+
+    # Re-archive the antennas-gitops repository
+    rm -f antennas-gitops.tgz
+    tar -zcf antennas-gitops.tgz antennas-gitops
+
+#
+# Deploy the application in a test environment and wait for the deployment
+# to complete.
+#
+deploy-test:
+  stage: test
+  needs: [ "helm-update" ]
+  environment: test
+  image: quay.io/openshift/origin-cli:4.11
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+    tar -zxf antennas-gitops.tgz
+
+    # Download and install Helm
+    curl -sf https://get.helm.sh/helm-v3.10.1-linux-amd64.tar.gz | tar -zx --strip-components 1 -C /usr/local/bin linux-amd64/helm
+
+    # Generate the YAML manifests for the test environment
+    helm dependency build antennas-gitops
+    helm template antennas antennas-gitops --values antennas-gitops/values-test.yaml > test-manifests.yaml
+
+    # Apply the YAML manifests
+    oc apply -n antennas-test -f test-manifests.yaml
+
+    # Wait for the deployment to complete
+    oc rollout status deploy/antennas-front -n antennas-test --timeout=5m
+
+#
+# Run some integration tests in the test environment.
+#
+# Note: the test environment is hardcoded to always deploy on the "blue" target
+#
+integration-test:
+  stage: test
+  needs: [ "deploy-test" ]
+  image: registry.access.redhat.com/ubi8/ubi:8.6
+  script:
+    - echo "Running integration tests..."
+    - curl -vf http://antennas-front-blue.antennas-test.svc:8080/rest/incidents
+
+#
+# Commit the changes in the antennas-gitops repository so that ArgoCD can pick
+# them up.
+#
+deploy-prod:
+  stage: deploy
+  needs: [ "helm-update", "integration-test" ]
+  environment: production
+  image: docker.io/alpine/git:2.36.3
+  script: |
+    #!/bin/sh
+    set -Eeuo pipefail
+
+    # Inject git credentials
+    echo "https://ci:${GITLAB_ACCESS_TOKEN}@${ANTENNAS_GITOPS_REPOSITORY}" > ~/.git-credentials
+    chmod 600 ~/.git-credentials
+
+    tar -zxf antennas-gitops.tgz
+    chown $(id -u):$(id -g) -R antennas-gitops
+    cd antennas-gitops
+
+    # Commit the changes to the antennas-gitops repository
+    git config user.email "nmasse@redhat.com"
+    git config user.name "Gitlab-CI Bot"
+    git add values-prod.yaml
+    git commit -m 'update production image digest'    
+    git push
+```