Write a guide explaining how to use a pipeline to build & deploy an app

[kvijai82]

This would also cover using the OCP internal registry with the external route.

[mingcyu]

@kvijai82 Hi Vijai, are you on track to completing by the end of the week(friday, May 1st)?

[kvijai82]

@mingcyu yes I have the first pass done.

[kvijai82]

The following guide will walk you through the steps needed to run a pipeline to build your application, publish the image to a registry, and optionally deploy the application on your cluster.

1. Clone the kabanero-pipelines repo.
   • cd into the pipelines/sample-helper-files directory.
2. For this guide, we will use the one of the default pipelines, java-openliberty-build-deploy-pl, that is activated by the Kabanero operator. You can replace this with any of the other build-deploy-pl or your custom pipeline.
3. Make sure you have the appropriate storage setup to drive Tekton pipelines. If you have a dynamic storage provisioner available on your cluster there is nothing to do. If not you can setup a simple NFS babsed PV using the nfs-pv.yaml sample provided.
   • Note you would need to update the IP address before applying the file
   • Run oc apply nfs-pv.yaml
4. Create the secret for your github repo. You can skip this step if it's a public repo. For a private repo, follow the steps in Secrets section of https://kabanero.io/guides/working-with-pipelines/#getting-started.
5. Create the secret for your image registry.
   • If you are using the internal route of the internal registry of your OCP cluster, you do not have to configure a secret as long as the service account you are running the pipeline with has the right permissions. The kabanero-pipeline service account is setup with the appropriate permissions.
   • If you are using the external route of the internal registry of your OCP cluster, you do not have to configure a secret also as the pipeline will recognize the URL and translate it to the internal route of the registry automatically.
   • If you are using a private registry, follow the steps in Secrets section of https://kabanero.io/guides/working-with-pipelines/#getting-started to setup a secret for your registry.
6. Setup certificates or specify insecure connection for the registry access following the documentation in https://kabanero.io/guides/working-with-pipelines/#transport-layer-security-tls-verification-for-image-registry-access-in-pipelines.
7. Run the pipeline. There are multiple ways to do this. Please reference the section of running pipelines documentation and choose the method you would like to follow to run the pipeline.
8. Review the status of your run and logs using the documentation provided at https://kabanero.io/guides/working-with-pipelines/#checking-the-status-of-the-pipeline-run
9. When the pipeline run is complete, you can go to your registry to check if the application image is published.
10. If you ran the pipeline via the webhook, it will only deploy the application if you initiated the run via a pull request merge. If that's the case, continue to the next step to access your application.
11. You can run oc get apposodyapplications or check your pods to see your application pod running.
12. You will have to create a secret for your image registy and associate it with the new service account that was created by the appsody application for your application.
    • If you are using the internal route for the internal registry there is nothing to do as the service account has the necessary permissions.
    • For private registries and the external route of the internal registry, create the secret for your registry and link to the service account that matches your application name.

Below are the steps to create a secret and link to the service account

a. To find what is the service account of your application

# oc get deployments -n kabanero

NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE
codeready-operator                        1/1     1            1           28h
java-microprofile-0-2-26                  1/1     1            1           25h
kabanero-cli                              1/1     1            1           28h
kabanero-landing                          1/1     1            1           28h
kabanero-operator                         1/1     1            1           28h
kabanero-operator-admission-webhook       1/1     1            1           28h
kabanero-operator-collection-controller   1/1     1            1           28h
kabanero-operator-stack-controller        1/1     1            1           28h

Based on above results and the pipeline I ran the deployment was for java-microprofile-0-2-26. Note it down.

b. Use the above deployment name to find the serviceaccount

oc get deployments java-microprofile-0-2-26 -o yaml --output="jsonpath={.spec.template.spec.serviceAccount}"

java-microprofile-0-2-26

Note the serviceaccount, and to this serviceaccount you would need to link your secret which we will create further.

c. Now if you are running with internal image registry external route for example hostnamedefault-route-openshift-image-registry.apps.abc.com then you follow this step

You need to find a token using any serviceaccount other than one found in step a, which will be a password for creation of secret later.

oc get secret -o name | grep -m 1 kabanero-pipeline-token  | xargs oc describe

Name:         kabanero-pipeline-token-7f59v
Namespace:    kabanero
Labels:       <none>
Annotations:  kubernetes.io/created-by: openshift.io/create-dockercfg-secrets
              kubernetes.io/service-account.name: kabanero-pipeline
              kubernetes.io/service-account.uid: 26bfb3ef-1334-4033-acd6-c8bc32dd1ba4

Type:  kubernetes.io/service-account-token

Data
====
ca.crt:          5932 bytes
namespace:       8 bytes
service-ca.crt:  7133 bytes
token:           eyJhbGciOiJSUzI1NiIsImtpZCI6IkZiTVVvUkhENlJjdFJsa0ZLdF9xd2lFX0piRVVkMHh5RjVoV2JCOFhvTkEifQ.eyJpc3MiOiJrdWJlcm5ld

Note: Here we used serviceaccount kabanero-pipeline to generate its token since this serviceaccount has right permissions to access internal registry.

d. If you are running with your private image registry you do not need to follow step c of token creation, and you need to use your password of the private registry as your password while creating secret shown further.

e. Now create a secret for your image registry based on your registry url.

oc -n kabanero create secret docker-registry [name of secret] --docker-server=[your registry hostname URL] --docker-username=[your registry username] --docker-password=[your registry password]

example for internal image registry external route:

oc -n kabanero create secret docker-registry my-registry --docker-server=default-route-openshift-image-registry.apps.abc.com --docker-username=kabanero-pipeline --docker-password=[token value found earlier]

secret/my-registry created

example for private registry

oc -n kabanero create secret docker-registry my-registry --docker-server=team-image-registry-docker-local.com --docker-username=[registry username] --docker-password=[registry password]

f. Finally link your secret to the application deployment serviceaccount as below

$oc -n kabanero secrets link [deployment serviceaccount ] [secret name] --for=pull,mount

example :
$oc -n kabanero secrets link java-microprofile-0-2-26 my-registry --for=pull,mount

13. If you exposed a route for your application, check the routes (oc get routes for example) and test your application.

[aadeshpa]

@kvijai82 has opened an issue in docs repo for this guide to be updated: https://github.com/kabanero-io/docs/issues/403

[kvijai82]

Delivered content to doc team