To get familiar with how an Alfresco Engineer or a Solution Developer can build and use a deployment package for Kubernetes we have created a simple hello world app that you can use for reference as you get started.

The application consists of several components:

• Database
  • To store the data, postgres in our case
• Backend REST Service
  • To Create/Read/Update/Delete entries in the db
• Backend REST Service Deployment
  • For creating Docker images and Helm charts for the service
• Frontend UI
  • As the interface to the backend service
• Frontend UI Deployment
  • For creating Docker images and Helm charts for the UI

The components, how they are packaged and deployed is shown in the diagram below:

The interactions between the components is shown in the following diagram:

1. Create the namespace and secrets based on the instruction provided in SECRETS.md and set its name as an environment variable:

   export DESIREDNAMESPACE=example

2. Pull the infrastructure chart to the namespace based on the instruction provided here.

3. Get the infrastructure release name from the previous command and set it as a variable:

   export INFRARELEASE=knobby-wolf

4. Add the helm repository so that chart dependencies can be pulled:

   helm repo add alfresco-incubator http://kubernetes-charts.alfresco.com/incubator

5. Deploy the helm chart in your namespace.

   helm install alfresco-incubator/hello-world-app --namespace $DESIREDNAMESPACE

   Keep in mind that when running on AWS the app will trigger Kubernetes to generate an Elastic Load Balancer providing access to the application and service, so you will probably have to wait a bit until it gets created and you can access the application.

6. Check that the deployment worked by running the command below:

   kubectl get pods --namespace $DESIREDNAMESPACE

   You should see output something similar to below. The first time you deploy the status column will say ContainerCreating for a while as it needs to download the docker image. If the status column shows an error take a look at the Troubleshooting section.

   NAME                                                       READY     STATUS    RESTARTS   AGE
   your-bison-hello-world-app-backend-433440179-bd31c         1/1       Running   0          37m
   your-bison-hello-world-app-ui-4187005864-wl4bx             1/1       Running   0          37m
   your-bison-nginx-ingress-controller-289934240-f2sh1        1/1       Running   0          37m
   your-bison-nginx-ingress-default-backend-714929657-7ds77   1/1       Running   0          37m
   your-bison-postgresql-400070053-8mxpw                      1/1       Running   0          37m
   

1. Run the following command to get url for UI

   echo "http://$(kubectl get services $INFRARELEASE-nginx-ingress-controller -o jsonpath={.status.loadBalancer.ingress[0].hostname} --namespace $DESIREDNAMESPACE)/hello-ui/welcome"

2. Navigate to the returned URL to use the UI. The screenshot below shows what you should see.

   

3. To access different keys in the db just change "welcome" to the key you've created and you should be able to see the value set for that key. Check out the next steps to find out how you can create a new key.

1. Run the following command to get service

   echo "http://$(kubectl get services $INFRARELEASE-nginx-ingress-controller -o jsonpath={.status.loadBalancer.ingress[0].hostname} --namespace $DESIREDNAMESPACE)/hello-service/hello/"

2. Use the following curl command to test the REST API.

   curl [url-from-step-1]/welcome

   You should see the following output:

   {"key":"welcome","value":"Hello World!"}
   

3. To create a new key through the service use the following curl:

   curl -H "Content-Type: application/json" -d '{"key":"new-test-data","value":"Test 1,2,3"}' [url-from-step-1]

4. To access different keys in the db just change "welcome" to the key you've created and you should be able to see the value set for that key.

   curl [url-from-step-1]/new-test-data

For more examples on using the hello service you can import the postman collection into the Postman app and use it there.

1. Run the following command to get a list of your releases:

   helm ls --namespace $DESIREDNAMESPACE

2. Run the command below with the appropriate release name to uninstall the infrastructure and this deployment:

   helm delete --purge [release-name]

3. Ensure everything has been removed by running the following command:

   helm status [release-name]

   You should see the following output:

   LAST DEPLOYED: Thu Nov  2 12:16:56 2017
   NAMESPACE: example
   STATUS: DELETED
   

4. Delete the namespace.

   kubectl delete namespace $DESIREDNAMESPACE

If the deployment is not working correctly list the pods by executing:

kubectl get pods --namespace $DESIREDNAMESPACE

If a pod is showing an error in the Status column run the following command to get more detailed information:

kubectl describe pod <pod-name> --namespace $DESIREDNAMESPACE

If the events indicate there is a problem fetching the docker image check that the secret created in the Deploy section contains credentials. The easiest way to do this is to use the Kubernetes dashboard as shown in the screenshot below. Click the eye icon to see the secret contents.

To get to the dashboard type kubectl proxy and then navigate to http://localhost:8081/ui in a browser.

If the credentials are missing check they are present in ~/.docker/config.json, especially if you're running on a Mac as the "Securely store docker logins in macOS keychain" preference may be enabled by default.

If you get a response of http:// from the get-ui-url.sh or get-backend-url.sh when deploying to a cluster on AWS, it likely means the Elastic Load Balancer for the service failed to create successfully. This can sometimes happen due to limits in your AWS account.