README.md

Modified Guestbook k8s Example

Guestbook k8s example is meant to showcase how k14s tools work together with a realistic application.

This example is based on guestbook example from kubernetes/examples. Changes were done to remove unused functionality.

Install k14s Tools

Head over to k14s.io for installation instructions.

Deploy

git clone https://github.com/k14s/k8s-guestbook-example
cd k8s-guestbook-example/

Using k14s tools, deploy via:

kapp deploy -a guestbook -f <(ytt -f config/ | kbld -f-) --diff-changes

Above command does the following:

• generate configuration from config/ via ytt
  • no network access
  • see Directory Layout below for details
• build images (with Docker) from source directories (frontend/ and redis-slave/) via kbld
  • talks to Docker via Docker CLI and directly to registries
• deploys configuration to k8s cluster via kapp
  • talks to k8s API server

If you are using Minikube as your deployment target, run eval $(minikube docker-env) beforehand so that kbld can successfully shell out to Docker CLI. By default images are kept locally (not pushed).

If you are using remote cluster as your deployment target you will have to provide registry destination where images could be pushed and be accessible to the cluster. You will still need to have access to Docker CLI and be logged in so that pushes are successful.

docker login ...
kapp deploy -a guestbook -f <(ytt -f config/ --data-value push_images=true --data-value push_images_repo=docker.io/dkalinin | kbld -f-) -c

(Even if you are deploying to remote cluster, Minikube could be used for its Docker daemon; just make sure that your ~/.kube/config points to your remote cluster.)

Deploying to Online Playground

If you want to use online playground instead of your own cluster, head over to Katacoda Kubernetes Playground. You will have to set --data-value katacoda=true flag when using ytt and untaint master node, before proceeding with the above command. See comments in config/katacoda.yml for additional details.

kubectl taint nodes master node-role.kubernetes.io/master-

(Command does end with a hyphen.)

Viewing Frontend App

Once deployed successfully, you can access frontend service at 127.0.0.1:8080 in your browser via kubectl port-forward command:

kubectl port-forward svc/frontend 8080:80

You will have to restart port forward command after making changes as pods are recreated. Alternatively consider using k14s' kwt tool which exposes cluser IP subnets and cluster DNS to your machine and does not require any restarts:

sudo -E kwt net start

and open http://frontend.default.svc.cluster.local/.

Making Changes

Once deployed, feel free to make changes to the app, and re-run same command.

For example, change frontend/guestbook.php:

-$bg = getenv('GUESTBOOK_BG');
+$bg = 'yellow';

or change frontend/frontend.yml:

-  GUESTBOOK_BG: "#eee"
+  GUESTBOOK_BG: "yellow"

and run exactly same command as before:

kapp deploy -a guestbook -f <(ytt -f config/ ...any opts... | kbld -f -) --diff-changes

Note that during second deploy each tool will try to be as optimal as possible based on changes made:

• kbld (via Docker) will only rebuild affected layers/images
• kapp will only deploy resources that changed or were affected by the change

Directory Layout

• frontend/: frontend app (Apache2 + PHP + Redis client)
• redis-slave/: Dockerfile to configure Redis as a slave
• config/build.yml: configuration for kbld to manage images
• config/frontend.yml: frontend configuration
• config/frontend-scale.yml: separate configuration to scale up frontend
• config/redis-master.yml: configuration to deploy Redis in master mode
• config/redis-slave.yml: configuration to deploy Redis as a slave
• config/katacoda.yml: ytt overlays to customize deployment for Katacoda Playground
• config/values.yml: global configuration knobs

Highlighted Features

Here are some features of k14s tools as used in this example:

ytt

• several configuration files use data.values.redis_port value from config/values.yml
  • this feature is useful for organizing shared configuration in one place
• separate overlay configuration that customizes another resource
  • example: config/frontend-scale.yml

kbld

• easy to convert source code for frontend application and redis-slave into container images
  • source: config/build.yml
• swap one image for another via ImageOverrides configuration

kapp

• all configuration resources are tagged consistently, hence could be tracked
  • see kapp inspect -a guestbook and kapp inspect -a guestbook --tree
• label selectors on Service and Deployment resources are scoped to this application automatically
  • example: config/frontend.yml only specifies frontend: "" label, and kapp augments it with an application specific label
• kapp.k14s.io/update-strategy: fallback-on-replace annotation on Deployment resources allows to easily change any part of Deployment
  • by default if update is allowed by k8s, no forceful action will be taken
  • example: frontend Deployment
• kapp.k14s.io/versioned: "" annotation on ConfigMap resource allows us to change ConfigMap data and be certain that related Deployment resources will be updated with new values
  • example: frontend Deployment picks up env variables from frontend-config ConfigMap
• all pod logs from this application could be found via kapp logs -f -a guestbook

Join the Community and Make Carvel Better

Carvel is better because of our contributors and maintainers. It is because of you that we can bring great software to the community. Please join us during our online community meetings. Details can be found on our Carvel website.

You can chat with us on Kubernetes Slack in the #carvel channel and follow us on Twitter at @carvel_dev.

Check out which organizations are using and contributing to Carvel: Adopter's list