<commit_before># User Guide

This doc acts as a user guide for onboarding apps to the platform and then updating them.

The following Critical User Journeys (CUJs) are covered:

* [Installation](../README.md#pre-requisites)
* [Adding a new application (using CLI)](#adding-a-new-application-using-cli)
* [Adding a new feature/version of the application](#adding-a-new-featureversion-of-the-application)
  * [Testing the change locally with Skaffold](#testing-the-change-locally-with-skaffold)
  * [Setting up your change for production](#setting-up-your-change-for-production)
* [Deploying application to production clusters](#deploying-application-to-production-clusters)
* [Accessing the application](#accessing-the-application)
* [Promoting changes from Staging to Production](#promoting-changes-from-staging-to-production)
* [Adding a cluster to the platform](#adding-a-cluster-to-the-platform)
* [Deleting an application](#deleting-an-application)

## Adding a new application (using CLI)

The following instructions use a command line utility ([anthos-platform-cli](cli/) to onboard an application into the system.

1. Download the `anthos-platform-cli` binary to your machine. Take note of getting the binary for the correct operating system.

    [Mac OS](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-darwin-amd64)

    [Linux](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-linux-amd64)

    [Windows](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-windows-amd64)

1. After downloading the binary, rename it and make it executable:

  ```shell
  mv anthos-platform-cli-* anthos-platform-cli
  chmod +x anthos-platform-cli
  ```

1. Run the app creation command, provide an application name with the parameter `--name`, your configured GitLab hostname (i.e. gitlab.your.domain.com) with the parameter `--gitlab-hostname` and GitLab root user password with the parameter `--gitlab-token`:

  ```shell
  ./anthos-platform-cli add app --name $APP_NAME --gitlab-hostname $GITLAB_HOSTNAME --gitlab-token $GITLAB_ROOT_PASSWORD --template-name golang-template
  ```

## Adding a new feature/version of the application

The following steps are performed by a **developer**, and can be performed locally or in Cloud Shell.

### Testing the change locally with Skaffold

1. [Install skaffold](https://skaffold.dev/docs/install/)
1. [Install kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md#quickly-curl-the-latest)
1. Clone your app repository

`git clone <EMAIL>.1.vic.dev:go-app-1/go-test-app-1.git
cd go-test-app-1`

1. Get credentials for the shared dev cluster

  ```shell
  kubectx development
  ```

1. Create an Artifact Registry repository for your user.

  ```shell
  export PROJECT_ID=$(gcloud config get-value project)
  gcloud beta artifacts repositories create $USER --repository-format=Docker --location=us-central1
  gcloud beta artifacts repositories add-iam-policy-binding --member serviceAccount:tf-sa-dev-us-central1@${PROJECT_ID}.iam.gserviceaccount.com --role roles/artifactregistry.reader --location us-central1 $USER
  ```

1. Set up Docker authentication to the registry.

  ```shell
  gcloud beta auth configure-docker us-central1-docker.pkg.dev
  ```

1. Currently the dev cluster is not managed by ACM so it's likely necessary to create the Dev’s namespace.

  ```shell
  kubectl create namespace $USER
  kubens $USER
  ```

1. Create the Kubernetes Service Account used by the app.

  ```shell
  kubectl create serviceaccount <app-name>-ksa
  ```
  
1. Set your default repository for skaffold to use.

  ```shell
  export PROJECT_ID=$(gcloud config get-value project)
  skaffold config set default-repo us-central1-docker.pkg.dev/$PROJECT_ID/$USER
  ```

1. Run Skaffold in developer mode so that it rebuilds your application as it changes:

  ```shell
  skaffold dev --port-forward
  ```

1. Change code and look at the logs in your console to ensure the expected results. If you are running skaffold on your local machine, point your browser to `http://localhost:8080`, if in Cloud Shell hit the "Web Preview" button.

1. Commit code, push to branch and create a merge request.

1. After CI passes, merge the MR.

### Setting up your change for production

1. After your MR into your app succeeds, the CI pipeline will perform a few actions:  unit-test, build, kustomize, push-manifests.

1. The last step, push-manifests actually pushes a file into the app-env repo's staging branch, go check it out and you'll see the output:

   ```console
   remote: To create a merge request for staging, visit:
   remote:   https://gitlab.smcghee.dev/go-team-go/go-app-env/merge_requests/new?merge_request%5Bsource_branch%5D=staging
   ```

1. You can now find your app running in the staging cluster:

   ```shell
   kubectx staging
   kubectl get po -n go-test-app-1
   kubectl get svc -n go-test-app-1
   ```

1. You can port-forward the staging build as well:

   ```shell
   kubectl port-forward svc/go-test-app-1-app -n go-test-app-1 8080:8080
   ```

1. At this point your feature is ready to be deployed to production.  An Operator will perform this.

## Promoting changes from Staging to Production

The following steps are performed by an **Operator**.

1. Once you are ready to deploy whatever is in Staging to the Production clusters (you may pull in many changes from various developers), you will do so by creating a Merge Request in the ${APP}-env **staging** branch onto **master**.
1. In Gitlab UI, navigate to the ${APP}-env repo (not the ${APP} repo).
![env repo branch](../images/env-repo-branch.png)

1. Create a new MR (ie [https://GITLAB_HOSTNAME/go-team-go/go-app-env/merge_requests](https://gitlab.smcghee.dev/go-team-go/go-app-env/merge_requests))

1. Get a peer to approve this MR (or approve it yourself if you are feeling lucky)

1. Click "Merge".

1. The CICD in GitLab will kick off your deployment to all clusters, in order:
![Production pipeline](../images/prod-deployment-pipeline-ui.png)

1. You are live in all production clusters!

If you want to add another cluster (like asia-east1 in the above screenshots), read on!
<commit_msg>update app docs<commit_after># User Guide

This doc acts as a user guide for onboarding apps to the platform and then updating them.

The following Critical User Journeys (CUJs) are covered:

* [Installation](../README.md#pre-requisites)
* [Adding a new application (using CLI)](#adding-a-new-application-using-cli)
* [Adding a new feature/version of the application](#adding-a-new-featureversion-of-the-application)
  * [Testing the change locally with Skaffold](#testing-the-change-locally-with-skaffold)
  * [Setting up your change for production](#setting-up-your-change-for-production)
* [Deploying application to production clusters](#deploying-application-to-production-clusters)
* [Accessing the application](#accessing-the-application)
* [Promoting changes from Staging to Production](#promoting-changes-from-staging-to-production)
* [Adding a cluster to the platform](#adding-a-cluster-to-the-platform)
* [Deleting an application](#deleting-an-application)

## Adding a new application (using CLI)

The following instructions use a command line utility ([anthos-platform-cli](cli/) to onboard an application into the system.

1. Download the `anthos-platform-cli` binary to your machine. Take note of getting the binary for the correct operating system.

    [Mac OS](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-darwin-amd64)

    [Linux](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-linux-amd64)

    [Windows](https://storage.googleapis.com/solutions-public-assets/anthos-platform-cli/v0.6.1/anthos-platform-cli-v0.6.1-windows-amd64)

1. After downloading the binary, rename it and make it executable:

    ```shell
    mv anthos-platform-cli-* anthos-platform-cli
    chmod +x anthos-platform-cli
    ```
1. Run the app creation command:

    ```shell
    ./anthos-platform-cli add app --name $APP_NAME --gitlab-hostname $GITLAB_HOSTNAME --gitlab-token $GITLAB_ROOT_PASSWORD --template-name golang-template
    ```

    * `--name` Application name (i.e. `go-app`)
    * `--gitlab-hostname` Your configured GitLab hostname (i.e. gitlab.your.domain.com)
    * `--gitlab-token` GitLab root user password with the parameter


## Adding a new feature/version of the application

The following steps are performed by a **developer**, and can be performed locally or in Cloud Shell.

### Testing the change locally with Skaffold

1. [Install skaffold](https://skaffold.dev/docs/install/)
1. [Install kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md#quickly-curl-the-latest)
1. [Install kubectx/kubens](https://github.com/ahmetb/kubectx/releases)
1. Clone your app repository (example uses the `$APP_NAME` go-app)

    ```shell
    git clone git@$GITLAB_HOSTNAME:$APP_NAME/$APP_NAME.git
    cd $APP_NAME
    ```

1. Get your shared dev cluster kube context

    ```shell
    gcloud container clusters get-credentials dev-central1
    ```

    Lists your context(s)
    ```shell
    kubectx
    ```

    Rename your context
    ```shell
    kubectx development=$DEV_KUBE_CONTEXT
    ```

1. Switch to the shared dev cluster context

    ```shell
    kubectx development
    ```

1. Create an Artifact Registry repository for your user.

    ```shell
    export PROJECT_ID=$(gcloud config get-value project)
    gcloud beta artifacts repositories create $USER --repository-format=Docker --location=us-central1
    gcloud beta artifacts repositories add-iam-policy-binding --member serviceAccount:tf-sa-dev-us-central1@${PROJECT_ID}.iam.gserviceaccount.com --role roles/artifactregistry.reader --location us-central1 $USER
    ```

1. Set up Docker authentication to the registry.

    ```shell
    gcloud beta auth configure-docker us-central1-docker.pkg.dev
    ```

1. Currently the dev cluster is not managed by ACM so it's likely necessary to create the Dev’s namespace.

    ```shell
    kubectl create namespace $USER
    kubens $USER
    ```

1. Create the Kubernetes Service Account used by the app.

    ```shell
    kubectl create serviceaccount $APP_NAME-ksa
    ```

1. Set your default repository for skaffold to use.

    ```shell
    export PROJECT_ID=$(gcloud config get-value project)
    skaffold config set default-repo us-central1-docker.pkg.dev/$PROJECT_ID/$USER
    ```

1. Run Skaffold in developer mode so that it rebuilds your application as it changes:

    ```shell
    skaffold dev --port-forward
    ```

1. Change code and look at the logs in your console to ensure the expected results. If you are running skaffold on your local machine, point your browser to `http://localhost:8080`, if in Cloud Shell hit the "Web Preview" button.

1. Commit code, push to branch and create a merge request.

1. After CI passes, merge the MR.

### Setting up your change for production

1. After your MR into your app succeeds, the CI pipeline will perform a few actions: unit-test, build, kustomize, push-manifests.

1. The last step, push-manifests actually pushes a file into the app-env repo's staging branch, go check it out and you'll see the output:

    ```console
    remote: To create a merge request for staging, visit:
    remote:   https://gitlab.smcghee.dev/go-team-go/go-app-env/merge_requests/new?merge_request%5Bsource_branch%5D=staging
    ```

1. You can now find your app running in the staging cluster:

     ```shell
     kubectx staging
     kubectl get po -n $APP_NAME
     kubectl get svc -n $APP_NAME
     ```

1. You can port-forward the staging build as well:

     ```shell
     kubectl port-forward svc/$APP_NAME-app -n $APP_NAME 8080:8080
     ```

1. At this point your feature is ready to be deployed to production.  An Operator will perform this.

## Promoting changes from Staging to Production

The following steps are performed by an **Operator**.

1. Once you are ready to deploy whatever is in Staging to the Production clusters (you may pull in many changes from various developers), you will do so by creating a Merge Request in the ${APP}-env **staging** branch onto **master**.
1. In Gitlab UI, navigate to the ${APP}-env repo (not the ${APP} repo).
![env repo branch](../images/env-repo-branch.png)

1. Create a new MR (ie `https://$GITLAB_HOSTNAME/$APP_NAME/$APP_NAME-env/merge_requests`)

1. Get a peer to approve this MR (or approve it yourself if you are feeling lucky)

1. Click "Merge".

1. The CICD in GitLab will kick off your deployment to all clusters, in order:
![Production pipeline](../images/prod-deployment-pipeline-ui.png)

1. You are live in all production clusters!

If you want to add another cluster (like asia-east1 in the above screenshots), read on!

{'fraction_non_alphanumeric': 0.1065252478671893, 'fraction_numerical': 0.011912996695104143, 'mean_word_length': 3.910188679245283, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '291901', 'n_tokens_mistral': 4097, 'n_tokens_neox': 3867, 'n_words': 1401}