kabanero-tekton-example

Example implementation of a Tekton pipeline that deploys an Appsody project on a Kabanero managed environment running on OpenShift or OKD.

Introduction

This repo contains an example of a Tekton pipeline that builds and deploys an application created with Appsody to a Kabanero managed cluster.

Prerequisites

In order to run this example, the following prerequisites are required:

1. You have access to an OpenShift or OKD cluster and have installed the Kabanero operator.

   Manual installation of the Kabanero operator
   
   1) Create a "kabanero" namespace using "sudo oc create namespace kabanero" followed by "oc project kabanero" to set your context to the new namespace.
   2) oc apply -f https://raw.githubusercontent.com/kabanero-io/kabanero-operator/master/deploy/dependencies.yaml
   3) oc apply -f https://raw.githubusercontent.com/kabanero-io/kabanero-operator/master/deploy/releases/0.0.1/kabanero-operator.yaml
   4) oc apply -f https://raw.githubusercontent.com/kabanero-io/kabanero-operator/master/config/samples/full.yaml

2. You have installed Istio on your cluster. Istio is not yet installed by the Kabanero operator.

   Manual installation of Istio
   
   1) oc adm policy add-scc-to-user anyuid -z istio-ingress-service-account -n istio-system
   2) oc adm policy add-scc-to-user anyuid -z default -n istio-system
   3) oc adm policy add-scc-to-user anyuid -z prometheus -n istio-system
   4) adm policy add-scc-to-user anyuid -z istio-egressgateway-service-account -n istio-system
   5) oc adm policy add-scc-to-user anyuid -z istio-citadel-service-account -n istio-system
   6) oc adm policy add-scc-to-user anyuid -z istio-ingressgateway-service-account -n istio-system
   7) oc adm policy add-scc-to-user anyuid -z istio-cleanup-old-ca-service-account -n istio-system
   8) oc adm policy add-scc-to-user anyuid -z istio-mixer-post-install-account -n istio-system
   9) oc adm policy add-scc-to-user anyuid -z istio-mixer-service-account -n istio-system
   10) oc adm policy add-scc-to-user anyuid -z istio-pilot-service-account -n istio-system
   11) oc adm policy add-scc-to-user anyuid -z istio-sidecar-injector-service-account -n istio-system
   12) oc adm policy add-cluster-role-to-user cluster-admin -z istio-galley-service-account -n istio-system
   13) oc adm policy add-scc-to-user anyuid -z cluster-local-gateway-service-account -n istio-system
   14) kubectl apply --filename https://github.com/knative/serving/releases/download/v0.4.0/istio-crds.yaml &&
   curl -L https://github.com/knative/serving/releases/download/v0.4.0/istio.yaml \
     | sed 's/LoadBalancer/NodePort/'
     | kubectl apply --filename -

3. You have created an application using the Appsody CLI, and your code is in a GitHub repository. [TODO] These instructions rely on that github project using https and being a public repository. We would have to extend the secrets section here to document using a private github repo with a github token secret.

4. Your code repository includes a Knative Serving manifest file called appsody-service.yaml. We’ll discuss this aspect in more detail later on.

5. Your Kubernetes cluster can access a Docker registry, such as Docker Hub (it can pull and push images). Alternatively, you can use the local Docker registry provided by OpenShift. [TODO] Need instructions or more info, guide won’t fully cover that suggestion.

6. [TODO] If the webhook provided by the Tekton expiramental webhook extension is to be demonstrated here, then we must document how to manually install 1) Tekton dashboard 2) Knative sources 3) Tekton webhook extension. That is all covered from https://github.com/tektoncd/experimental/tree/master/webhooks-extension

7. Your Kubernetes cluster can access a Docker registry, such as Docker Hub (it can pull and push images). Alternatively, you can use the local Docker registry provided by OpenShift. [TODO] Need instructions or more info, guide won’t fully cover that suggestion.

Setting up the pipeline

This repo contains the manifests for the resources that you need to create on your cluster in order to run the Tekton pipeline for Appsody. Ensure that you are creating all resources in the previously created "kabanero" namespace.

1. Since the Tekton pipeline needs to deploy to the cluster itself, you want to ensure that it runs under an identity that has cluster administrator privileges.

   For this reason, create a service account and the appropriate cluster role binding by issuing:

   kubectl apply -f appsody-service-account.yaml
   kubectl apply -f appsody-cluster-role-binding.yaml

   The previous commands set up a service account called appsody-sa and grant the cluster-admin role to it. The pipeline you are going to create uses this service account.

2. Next, create a secret to hold the login credentials for the Docker registry where you want to push the result of your sample pipeline build. Notice the "annotations" field includes URL patterns. In the example below, this secret will be used when the pipeline build is attempting to authenticate with https://index.docker.io/v1/. my-docker-secret is the name of secret that we will reference later. You may use any name you wish.

   apiVersion: v1
   kind: Secret
   metadata:
     name: my-docker-secret
     annotations:
       tekton.dev/docker-0: https://index.docker.io/v1/
   type: kubernetes.io/basic-auth
   stringData:
     username: <your docker userid>
     password: <your docker password>

   Edit the yaml file my-docker-secret.yaml, making sure to replace the username and password values with your own values. Then run:

   kubectl apply -f my-docker-secret.yaml

3. Make the Docker registry credentials available to the pipeline by adding your docker secret to the appsody-sa service account. This can be accomplished by editing the service account, using the following command:

   kubectl edit serviceaccount appsody-sa

   An editor opens up. Add your secret to the list of secrets, as shown in the example below:

   ...
   secrets:
   - name: appsody-sa-token-ldzbq
   - name: my-docker-secret

   Save the changes.

4. Now, create the pipeline task and the pipeline definition. We have a simple pipeline, with a single task that performs the various steps of building and deploying the project:

   kubectl apply -f appsody-build-task.yaml
   kubectl apply -f appsody-build-pipeline.yaml

5. The pipeline requires the definition of two resources in order to operate:

   • The definition of the Docker image that is built and deployed by the pipeline itself

   • The location of the GitHub project that contains your Appsody code

     For this reason, you need to edit the appsody-pipeline-resources.yaml. Change the value of the Docker image url to match your settings:

     ...
     spec:
       params:
       - name: url
         value: index.docker.io/your-userid/my-appsody-image
         type: image

     And change the definition of your GitHub project:

     ...
     spec:
       params:
       - name: revision
         value: master
       - name: url
         value: https://github.com/your-userid/appsody-test-build

6. Once you have edited the resources, apply them to your cluster:

kubectl apply -f appsody-pipeline-resources.yaml

The Tekton pipeline is now fully set up.

A few words on the required deployment manifest

As we mentioned earlier, the pipeline is designed to deploy your application to the Kubernetes cluster as a Knative Serving service. The pipeline expects a deployment manifest located within your project - specifically, it expects to run kubectl apply against a file named appsody-service.yaml.

Here we provide an example of such a deployment manifest:

apiVersion: serving.knative.dev/v1alpha1
kind: Service
metadata:
  name: appsody-project
spec:
  runLatest:
    configuration:
      revisionTemplate:
        spec:
          container:
            image: mydockeraccount/appsody-project
            imagePullPolicy: Always
            ports:
            - containerPort: 3000

The file can be located anywhere within your project, since the pipeline will discover it.

Notice that the image url must match the definition of the Docker image resource that you created for the pipeline. The containerPort must be set to the port number on which the server inside the Appsody stack is configured to listen.

One way to obtain a manifest file that has all the matching settings is to run the appsody deploy command, as described in the Appsody documentation.

It must be noted, however, that the pipeline can work with any deployment manifest - not limited to Knative Serving services. Its current implementation applies whatever deployment manifest is contained in appsody-service.yaml.

The file name can be modified by simply changing the relevant line in appsody-build-pipeline.yaml, as pointed out here:

      params:
      - name: appsody-deploy-file-name
        value: appsody-service.yaml

Also, if you wanted to retrieve a deployment manifest from a different repository, rather than assuming its presence in the application code repository, you could modify this section of appsody-build-task.yaml:

    - name: install-knative
      image: lachlanevenson/k8s-kubectl
      command: ['/bin/sh']
      args: ['-c', 'find /workspace/extracted -name ${YAMLFILE} -type f|xargs kubectl apply -f']
      env:
        - name: YAMLFILE
          value: ${inputs.params.appsody-deploy-file-name}

The implementation we have provided assumes the deployment manifest is in the workspace\extracted directory, which contains a clone of the source repository - but it could be adjusted to obtain that file from a different source.

Running the pipeline manually

This repo provides a manual trigger (via a PipelineRun resource) that you can use to kick off the pipeline on your cluster.

Run the following command:

kubectl apply -f appsody-pipeline-run.yaml

A new pod will be launched in the "kabanero" namespace with the name similar to:

appsody-manual-pipeline-run-appsody-build-t9g87-pod-6c00e4

To view the logs from the running pipeline, use this command, tailored for the specific id of your pod:

kubectl logs appsody-manual-pipeline-run-appsody-build-t9g87-pod-6c00e4 -n kabanero --all-containers

In that output, you will see the output from the pipeline build.

To re-run another build, first delete the existing pipeline-run before re-running the apply command:

kubectl delete -f appsody-pipeline-run.yaml

Triggering the pipeline via a git webhook

[TODO] Include information about using the Tekton dashboard webhook extension to setup the git webhook. This would include creating a webhook using the "appsody-build-pipeline" previously defined in these instructions.