Managing Applications with Application Delivery

This tutorial walks you through configuring a deployment of NGINX with Application Delivery. The deployment runs on two environments, staging and prod. The prod environment uses regular configuration, while staging uses a slightly modified one.

For more information on Application Delivery, see the Concept document.

Requirements

To complete this tutorial, you will need the following:

  • Git installed locally.
  • A GitHub or GitLab account with permissions to create a private repository. Application Delivery supports only GitHub and GitLab repositories.
  • A cluster running GKE 1.15 or higher.
  • A user with clusterAdmin privileges.

Before you begin

Before you start, make sure you have performed the following tasks:

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

  1. Run gcloud init and follow the directions:

    gcloud init

    If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

    gcloud init --console-only
  2. Follow the instructions to authorize gcloud to use your Google Cloud account.
  3. Create a new configuration or select an existing one.
  4. Choose a Google Cloud project.
  5. Choose a default Compute Engine zone.

Using gcloud config

  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • If you are working with regional clusters, set your default compute region:
    gcloud config set compute/region [COMPUTE_REGION]
  • Update gcloud to the latest version:
    gcloud components update
  • Add SSH keys to your GitHub or GitLab account.
  • Test your keys with ssh:

    GitHub

    ssh -T git@github.com

    GitLab

    ssh -T git@gitlab.com

    You might be asked to confirm connection details or your key passphrase. If the connection succeeds, a message is printed on the terminal.

Setting up Application Delivery

To use Application Delivery, you can create a new cluster with it enabled, or enable it on an existing GKE cluster running version 1.15 and higher. Then, you install appctl, the Application Delivery command line tool.

Create a new cluster with Application Delivery

You can create a new cluster with Application Delivery enabled using gcloud or the Google Cloud Console.

gcloud

Choose a cluster version of 1.15.x or higher.

gcloud beta container clusters create [CLUSTER_NAME] --cluster-version [CLUSTER_VERSION] --addons ApplicationManager

Console

  1. Go to Create a Kubernetes cluster on the Google Cloud Console.
  2. Name your cluster.
  3. Choose a Master version of 1.15.x or higher.
  4. Select any additional options you would like to enable.
  5. Scroll to the bottom and click on Availability, networking, security, and additional features.
  6. Under Additional features, check the Enable Application Manager box.
  7. Click Create.

Enabling Application Delivery on an existing cluster

You can enable Application Delivery on an existing using gcloud or the Google Cloud Console.

gcloud

gcloud beta container clusters update [CLUSTER_NAME] --update-addons ApplicationManager=ENABLED

Console

  1. Go to the Clusters page on the Google Cloud Console.
  2. Select the cluster where you want to install Application Delivery. The Cluster Details screen appears.
  3. Click Edit.
  4. Click Add-ons. The menu expands.
  5. Under Application Manager, choose Enabled.
  6. Click Save to update your cluster.

Confirming installation

To check the status of your Application Delivery installation, run the following kubectl commands.

kubectl get pods kalm-controller-manager-0 -n kalm-system
kubectl get pods application-controller-manager-0 -n application-system

When Application Delivery is running, both commands return that there is exactly one pod with a STATUS of Running.

NAME                        READY   STATUS    RESTARTS   AGE
kalm-controller-manager-0   2/2     Running   0          1h
NAME                               READY   STATUS    RESTARTS   AGE
application-controller-manager-0   1/1     Running   0          1h

Install appctl

You install appctl, the Application Delivery command line tool, with gcloud.

gcloud components install appctl

After enabling Application Delivery on a cluster and installing appctl, you are ready to deploy your first application.

Deploying an application

The following sections describe how to:

  1. Create git repositories with appctl.
  2. Create a base configuration.
  3. Create one or more environments for your deployment.
  4. Optionally, apply configuration overlays to your environments in your application repository.
  5. Create a release candidate in the form of a pull or merge request.
  6. Deploy your release.

Creating repositories

You create repositories for Application Delivery on GitHub or GitLab or with appctl.

  1. Change to the directory where you would like to create your application directory.
  2. Create your Application Delivery repositories with appctl.

GitHub

appctl init [APPLICATION_NAME] \
--app-config-repo=github.com/[USER_NAME]/[APPLICATION_NAME]

For example, if your GitHub username is octocat and you want to create an application named myapp, run the following:

appctl init myapp --app-config-repo=github.com/octocat/myapp

GitLab

appctl init [APPLICATION_NAME] \
--app-config-repo=gitlab.com/[USER_NAME]/[APPLICATION_NAME]

For example, if your GitLab username is alice and you want to create an application named myapp, run the following:

appctl init myapp --app-config-repo=gitlab.com/alice/myapp

appctl prompts you to confirm your new private repositories.

appctl creates two remote private git repositories:

  • The application repository github.com/[USER_NAME]/[APPLICATION_NAME]. This repository is cloned to the current directory.
  • The deployment repository github.com/[USER_NAME]/[APPLICATION_NAME]-deployment.

For more information on the content and structure of these repositories, see the Application delivery concept guide.

Creating a base configuration

  1. Change your working directory to your application repository. For example, if you used the application name myapp, run

    cd myapp
  2. Create the configuration for your Kubernetes workload. This can be any valid Kubernetes deployment.

    The following configuration defines an application named nginx, which deploys 3 replicas of the nginx container. Copy the configuration into the file config/base/myapp.yaml . If you would like to enable a LoadBalancer, uncomment the line type: LoadBalancer.

    #myapp/config/base/myapp.yaml
    
    apiVersion: v1
    kind: Service
    metadata:
      name: nginx
      labels:
        app: nginx
    spec:
      # if your cluster supports it, uncomment the following to automatically create
      # an external load-balanced IP for the frontend service.
      # type: LoadBalancer
      ports:
        - port: 80
      selector:
        app: nginx
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: nginx
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: nginx:1.7.9
            ports:
            - containerPort: 80
    
  3. Configure Application Delivery to apply this configuration to the base. Paste the following into config/base/kustomization.yaml.

    #config/base/kustomization.yaml
    
    resources:
      - myapp.yaml
    

Testing and pushing your configuration

  1. From your application repository directory, test your configuration with kubectl apply -k:

    kubectl apply -k config/base/ --dry-run -o yaml

    If your configuration is valid, kubectl prints the YAML that will be deployed to your cluster when it is applied.

  2. After you have validated your YAML, create and push a commit in your application repository.

    git add .
    git commit -m "Creating [APPLICATION_NAME]"
    git push origin master

Adding a release environment

Application Delivery deploys your application into environments. You add environments for your releases with appctl.

  1. Change to your application repository root directory (for example, cd myapp).
  2. Create your environment with appctl

    appctl env add [ENVIRONMENT_NAME] --cluster=[CLUSTER_NAME]

    appctl creates a git commit containing a scaffolded Kustomize configuration.

    For example, to add the staging and prod environments to the cluster application-cluster, run the following command:

    appctl env add staging --cluster=application-cluster
    appctl env add prod --cluster=application-cluster
  3. Optionally, you can see the changes Application Delivery made in your Git repository with git log.

    git log -p *
  4. Push the configuration to your application repository.

    git push origin master

Optional: Checking your deployment repository

  1. Open the GitHub or GitLab page for your deployment repository. For example, if your GitHub username is octocat and you created an application named myapp, the URL is https://github.com/octocat/myapp-deployment. From this page, you can see the branches that were created for each environment.

Deploying an environment

To deploy an environment with Application Delivery, you:

  1. Create a version with git tag and push that tag.

    git tag [VERSION]
    git push origin [VERSION]

    For example, to push version v0.1.0, run the following commands:

    git tag v0.1.0
    git push origin  v0.1.0

  2. Use appctl prepare to nominate the currently tagged version and generate a pull request in the deployment repository for review.

    appctl prepare [ENVIRONMENT_NAME]

    For example, to use the staging environment, run the following command:

    appctl prepare staging

    If appctl completed the commit to the deployment repository, it prints a URL to create a pull request.

    Click to create a "Pull Request":
    "https://github.com/octocat/myapp-deployment/compare/[VERSION_BRANCH]"
    

    Open the URL in your browser. The Comparing Changes screen (in GitHub) or the New Merge Request screen (in GitLab) appears.

  3. Use GitHub or GitLab to review and approve the pull request.

  4. After the pull request has been approved, use appctl apply to complete the deployment.

    appctl apply [ENVIRONMENT_NAME]

    For example, to deploy changes to the staging environment, run the following:

    appctl apply staging
  5. Confirm that your application is running with kubectl or from the Google Cloud Console.

    kubectl

    Use kubectl describe to view the status of your application,

     kubectl get releasetracks.app.gke.io [APPLICATION_NAME] -n 
    [APPLICATION_NAME]-[ENVIRONMENT_NAME] -w

    Where [APPLICATION_NAME] is the name of your application repository, and [ENVIRONMENT_NAME] is your environment name.

    For example, to check the status of the staging environment of the application named myapp, run the following command:

    kubectl get releasetracks.app.gke.io myapp -n myapp-staging

    Google Cloud Console

    To see status and version information for your applications deployed with Application Delivery see the GKE Applications page on Google Cloud Console.

Promoting a release

  1. To promote a release candidate from one environment to another, run the following command:

    appctl prepare [TARGET_ENVIRONMENT_NAME] \
    --from-env [SOURCE_ENVIRONMENT_NAME]

    Where [TARGET_ENVIRONMENT_NAME] is the name of the environment that you wish to deploy the release candidate currently running on [SOURCE_ENVIRONMENT_NAME].

    For example, to promote staging to prod run:

    appctl prepare prod --from-env staging

  2. Use GitHub or GitLab to review and approve the pull request.

  3. To deploy the release candidate to the target environment, run the following command:

    appctl apply [TARGET_ENVIRONMENT_NAME]

    For example, to deploy to the prod environment, run:

    appctl apply prod

Changing an environment's configuration

This section assumes you have a staging environment configured as in the previous steps. You may need to adapt these instructions for your use.

In this section, you change the parameters for the staging environment using a kustomize overlay. After making the change, you push and tag your changes in git. Application Delivery will update your cluster.

  1. Create the file config/envs/staging/patch-replicas.yaml, and copy the following text into it. This updates the configuration in the staging environment to run one replica instead of three replicas.

    #config/envs/staging/patch-replicas.yaml
    
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 1
    
  2. Edit config/envs/staging/kustomization.yaml and add patch-replicas.yaml to a new collection named patchesStrategicMerge.

    #config/envs/staging/kustomization.yaml
    namespace: myapp-staging
    bases:
       - ../../base
    patchesStrategicMerge:
       - patch-replicas.yaml
    

    You can also add environment-specific annotations in this overlay. The following example adds an annotation named oncall-team to add all resources under this environment. For more information, see Kustomize file fields.

    #config/envs/staging/kustomization.yaml
    
    #Don't change the namespace field
    namespace: myapp-staging
    bases:
       - ../../base
    patchesStrategicMerge:
       - patch-replicas.yaml
    commonAnnotations:
      oncall-team: staging-oncall@foo.bar
    
  3. Test your configuration with kubectl apply -k:

    kubectl apply -k config/envs/staging/ --dry-run -o yaml

  4. Add and commit your changes.

    git add .
    git commit -m "[COMMIT_MESSAGE]"
    git push origin master

    Where [COMMIT_MESSAGE] is a message that describes your changes.

  5. Create a version with git tag and push it.

    git tag [VERSION]
    git push origin  [VERSION]
  6. Use appctl prepare to generate a pull request in the deployment repository for review.

    appctl prepare [ENVIRONMENT_NAME]
  7. Follow the link to create a GitHub or GitLab pull request.

  8. Look over the contents of your pull request. Application Delivery makes a one-line change that sets the value of replicas to 1.

  9. Approve the pull request with GitHub or GitLab

  10. Use appctl apply to apply the changes.

    appctl apply staging

Rolling back configuration changes

You can use appctl apply to roll back to a previous release.

appctl apply
[TARGET_ENVIRONMENT_NAME] --from-tag [GIT_TAG]

Where [TARGET_ENVIRONMENT_NAME] is the name of the environment that you wish to deploy the release tagged with [GIT_TAG].

Using appctl in scripts

The appctl tool is interactive, expects for user input, by default. If you want to run appctl in a script, container, or pipelines, set the environment variable APPCTL_INTERACTIVE to false.

For example, in the bash shell, run the following command.

export APPCTL_INTERACTIVE=false

Information on specific appctl commands is available with appctl help [COMMAND]. For example, to get help with appctl prepare, run appctl help prepare .

Uninstalling Application Manager

To remove the application running in your cluster, you delete all Namespaces created with new environments. For all of your environments and clusters, repeat the following commands:

  1. Switch to the cluster for a given environment

    $ kubectl config use-context ${CONTEXT_OF_ENV_CLUSTER}
  2. Delete the namespace where your application for this environment is running

     kubectl delete ns [APPLICATION_NAME]-[ENVIRONMENT_NAME]

    Where [APPLICATION_NAME] is the name of your application repository, and [ENVIRONMENT_NAME] is your environment name.

  3. From GitHub or GitLab, delete the two git repositories created by appctl.

  4. Delete your local application directory:

    rm -rf myapp/
  5. You can disable Application Delivery in your cluster from gcloud or the Google Cloud Console:

    gcloud

    gcloud beta container clusters update [CLUSTER_NAME] \
    --update-addons ApplicationManager=DISABLED

    Console

    1. Go to the Clusters page on the Google Cloud Console and select the cluster that you want to update.
    2. Click Edit. The Edit clusters screen appears.
    3. Click Add-ons
    4. Select under Application Manager, choose Disabled.
    5. Click Save to update your cluster.

What's Next?

Read more about Kustomize.