simple-app-example

Example repo shows how to use tools from carvel dev: ytt, kbld, kapp, imgpkg, and kwt to work with a simple Go app on Kubernetes.

Associated blog post: Deploying Kubernetes Applications with ytt, kbld, and kapp.

Are the Carvel Tools installed

Test to see if the tools are installed by running the following code snippets:

kapp version
kbld version
ytt version
imgpkg version
kwt version

If these tools are not installed, either contact someone with administrative privileges on your kubernetes cluster, or head over to carvel.dev for installation instructions.

Deploying the Application

Each top level step has an associated config-step-* directory. Refer to Directory Layout for details about files.

Step 0: Pushing an image to your repository

Uses . kbld . ytt . kapp . imgpkg

Why are we doing this? Docker has instituted rate limiting. We wish to avoid that situation, so we are going to pull the original image from dkalinin and store it in our docker compliant OCI registry, Harbor.

We will illustrate two ways to accomplish this task: a long way, and a short way. At the bottom of this section there is a third way to accompish this task, however, we are not going to illustrate it. That is left up to the consumer of this repository. In our opinion, the simplest way to do this is to use the imgpkg command.

The Long Way

Here's the long way.

First, it is convenient if you set your Registry in an environment variable. We are showing an example of HARBOR!

export HARBOR_DOMAIN=<your-registry>

Log into your OCI compliant registry

docker login ${HARBOR_DOMAIN} -u <your-login-username>

You will be asked to enter your password.

Now, pull the original Docker image (you can see this in the original repo we forked in the top left of the GitHub screen).

docker pull docker.io/dkalinin/k8s-simple-app

Now, retag the original image to something you want in your registry

docker image tag dkalinin/k8s-simple-app:latest ${HARBOR_DOMAIN}/<your-repository>/simple-app:<your-tag>

Now, push that new image into your registry and repository.

docker push ${HARBOR_DOMAIN}/<your-registry>/simple-app:<your-tag>

Log into your registry in the GUI and find your repository, and then find the docker pull command to use. We typically verify that an new image exists by pulling it from our regsitry. This is a simple way to verify that you actually pushed the image you want and can consume it later (pull).

docker pull ${HARBOR_DOMAIN}/<your-repository>/simple-app@sha256:<replace-with-the-sha-value>

The Short Way

Here's the second way of doing this. You need to have an up-to-date version of imgpkg.

imgpkg copy -i dkalinin/k8s-simple-app:latest --to-repo ${HARBOR_DOMAIN}/<your-repository>/simple-app

Third Option

Here's the third way to do this.

Warning: If you have forked this repository, you will need to edit the configuration files listed below to point to your own registry. You CANNOT simply run the following code as it was designed to be consumed by our lab participants. You will also have to edit the configuration files in the config-step-0-start directory to match your repository. DO NOT JUST RUN THESE COMMANDS!

docker login
docker login <your OCI compliant registry>
kapp deploy -a simple-app -c -f <(ytt -f config-step-0-start/ -v push_images_repo=<your_repository>/<your_project_name>/simple-app | kbld -f- )

Step 1: Deploying application

Introduces kapp for deploying k8s resources.

kapp deploy -a simple-app -f config-step-1-minimal/
kapp inspect -a simple-app --tree
kapp logs -f -a simple-app

Step 1a: Viewing application

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/simple-app 8080:80

You will have to restart port forward command after making any changes as pods are recreated. Alternatively consider using kwt 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://simple-app.default.svc.cluster.local/.

Step 1b: Modifying application configuration

Modify HELLO_MSG environment value from stranger to something else in config-step-1-minimal/config.yml, and run:

kapp deploy -a simple-app -f config-step-1-minimal/ --diff-changes

In following steps we'll use -c shorthand for --diff-changes.

Step 2: Configuration templating

Introduces ytt templating for more flexible configuration.

kapp deploy -a simple-app -c -f <(ytt -f config-step-2-template/)

ytt provides a way to configure data values from command line as well:

kapp deploy -a simple-app -c -f <(ytt -f config-step-2-template/ -v hello_msg=another-stranger)

New message should be returned from the app in the browser.

Step 2a: Configuration patching

Introduces ytt overlays to patch configuration without modifying original config.yml.

kapp deploy -a simple-app -c -f <(ytt -f config-step-2-template/ -f config-step-2a-overlays/custom-scale.yml)

Step 2b: Customizing configuration data values per environment

Requires ytt v0.13.0+.

Introduces use of multiple data values to show layering of configuration for different environment without modifying default values.yml.

kapp deploy -a simple-app -c -f <(ytt -f config-step-2-template/ -f config-step-2b-multiple-data-values/)

Step 3: Building container images locally

Introduces kbld functionality for building images from source code. This code relies on you having access to a Kubernetes cluster, a OCI compliant registry (like Harbor), AND you editing the config files in the config-step-3-build-local directory. DO NOT RUN THESE COMMANDS WITHOUT EDITING THE CONFIG files!

kapp deploy -a simple-app -c -f <(ytt -f config-step-3-build-local/ | kbld -f-)

Note that rerunning above command again should be a noop, given that nothing has changed.

Step 3a: Modifying application source code

In the config-step-3-build-local directory, uncomment fmt.Fprintf(w, "<p>local change</p>") line in app.go, and re-run above command:

kapp deploy -a simple-app -c -f <(ytt -f config-step-3-build-local/ | kbld -f-)

Observe that new container was built, and deployed. This change should be returned from the app in the browser.

Step 4: Clean up cluster resources

kapp delete -a simple-app

There is currently no functionality in kbld to remove pushed images from registry. There are instructions at the end of the large lab that will delete these images, and your instructor will run a clean-up script after class is finished.

Directory Layout

• app.go: simple Go HTTP server
• Dockerfile: Dockerfile to build Go app
• config-step-1-minimal/
  • config.yml: basic k8s Service and Deployment configuration for the app
• config-step-2-template/
  • config.yml: slightly modified configuration to use ytt features, such as data module and functions
  • values.yml: defines extracted data values used in config.yml
• config-step-2a-overlays/
  • custom-scale.yml: ytt overlay to set number of deployment replicas to 3
• config-step-3-build-local/
  • build.yml: tells kbld about how to build container image from source (app.go + Dockerfile)
  • config.yml: same as prev step
  • values.yml: same as prev step
• config-step-4-build-and-push/
  • build.yml: same as prev step
  • push.yml: tells kbld about how to push container image to remote registry
  • config.yml: same as prev step
  • values.yml: defines shared configuration, including configuration for pushing container images

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