From 7771d1b44821d54b5892042fe17bcd27c63b803c Mon Sep 17 00:00:00 2001 From: debuggy Date: Thu, 26 Sep 2019 17:13:39 +0800 Subject: [PATCH 1/2] Add getting started tutorial --- README.md | 5 ++ docs/tutorial.md | 125 +++++++++++++++++++++++++++++++++++++ examples/pod.yaml | 27 ++++++++ examples/volume-claim.yaml | 11 ++++ examples/volume.yaml | 14 +++++ 5 files changed, 182 insertions(+) create mode 100644 docs/tutorial.md create mode 100644 examples/pod.yaml create mode 100644 examples/volume-claim.yaml create mode 100644 examples/volume.yaml diff --git a/README.md b/README.md index 38a4a63a3a..fcb8c241f4 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ _If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPME - [How does kaniko work?](#how-does-kaniko-work) - [Known Issues](#known-issues) - [Demo](#demo) +- [Tutorial](#tutorial) - [Using kaniko](#using-kaniko) - [kaniko Build Contexts](#kaniko-build-contexts) - [Running kaniko](#running-kaniko) @@ -77,6 +78,10 @@ kaniko does not support building Windows containers. ![Demo](/docs/demo.gif) +## Tutorial + +For a detailed example of kaniko with local storage, please refer to a [getting started tutorial](./docs/tutorial.md). + ## Using kaniko To use kaniko to build and push an image for you, you will need: diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000000..298690dff2 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,125 @@ +# Getting Started Tutorial + +This tutorial is for beginners who want to start using kaniko and aims to establish a quick start test case. + +## Table of Content + +1. [Prerequisities](#Prerequisities) +2. [Prepare config files for kaniko](#Prepare-config-files-for-kaniko) +3. [Prepare the mounted directory in minikube](#Prepare-the-mounted-directory-in-minikube) +4. [Create a Secret that holds your authorization token](#Create-a-Secret-that-holds-your-authorization-token) +5. [Create resources in kubernetes](#Create-resources-in-kubernetes) +6. [Pull the image and test](#Pull-the-image-and-test) + +## Prerequisities + +- A Kubernetes Cluster. You could use [Minikube](https://kubernetes.io/docs/setup/minikube/) to deploy kubernetes locally, or use kubernetes service from cloud provider like [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/). +- A [dockerhub](https://hub.docker.com/) account to push built image public. + +## Prepare config files for kaniko + +After installing minikube, we should prepare several config files to create resources in kubernetes, which are: + +- [pod.yaml](../examples/pod.yaml) is for starting a kaniko container to build the example image. +- [volume.yaml](../examples/volume.yaml) is for creating a persistent volume used as kaniko build context. +- [volume-claim.yaml](../examples/volume-claim.yaml) is for creating a persistent volume claim which will mounted in the kaniko container. + +## Prepare the local mounted directory + +SSH into the cluster, and create a local directory which will be mounted in kaniko container as build context. Create a simple dockerfile there. + +> Note: To ssh into cluster, if you use minikube, you could use `minikube ssh` command. If you use cloud service, please refer to official doc, such as [Azure Kubernetes Service](https://docs.microsoft.com/en-us/azure/aks/ssh#code-try-0). + +```shell +$ mkdir kaniko && cd kaniko +$ echo 'FROM ubuntu' >> dockerfile +$ echo 'ENTRYPOINT ["/bin/bash", "-c", "echo hello"]' >> dockerfile +$ cat dockerfile +FROM ubuntu +ENTRYPOINT ["/bin/bash", "-c", "echo hello"] +$ pwd +/home//kaniko # copy this path in volume.yaml file +``` + +> Note: It is important to notice that the `hostPath` in the volume.yaml need to be replaced with the local directory you created. + +## Create a Secret that holds your authorization token + +A Kubernetes cluster uses the Secret of docker-registry type to authenticate with a docker registry to push an image. + +Create this Secret, naming it regcred: + +```shell +kubectl create secret docker-registry regcred --docker-server= --docker-username= --docker-password= --docker-email= +``` + +- `` is your Private Docker Registry FQDN. (https://index.docker.io/v1/ for DockerHub) +- `` is your Docker username. +- `` is your Docker password. +- `` is your Docker email. + +This secret will be used in pod.yaml config. + +## Create resources in kubernetes + +```shell +# create persistent volume +$ kubectl create -f volume.yaml +persistentvolume/dockerfile created + +# create persistent volume claim +$ kubectl create -f volume-claim.yaml +persistentvolumeclaim/dockerfile-claim created + +# check whether the volume mounted correctly +$ kubectl get pv dockerfile +NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE +dockerfile 10Gi RWO Retain Bound default/dockerfile-claim local-storage 1m + +# create pod +$ kubectl create -f pod.yaml +pod/kaniko created +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +kaniko 0/1 ContainerCreating 0 7s + +# check whether the build complete and show the build logs +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +kaniko 0/1 Completed 0 34s +$ kubectl logs kaniko +➜ kubectl logs kaniko +INFO[0000] Resolved base name ubuntu to ubuntu +INFO[0000] Resolved base name ubuntu to ubuntu +INFO[0000] Downloading base image ubuntu +INFO[0000] Error while retrieving image from cache: getting file info: stat /cache/sha256:1bbdea4846231d91cce6c7ff3907d26fca444fd6b7e3c282b90c7fe4251f9f86: no such file or directory +INFO[0000] Downloading base image ubuntu +INFO[0001] Built cross stage deps: map[] +INFO[0001] Downloading base image ubuntu +INFO[0001] Error while retrieving image from cache: getting file info: stat /cache/sha256:1bbdea4846231d91cce6c7ff3907d26fca444fd6b7e3c282b90c7fe4251f9f86: no such file or directory +INFO[0001] Downloading base image ubuntu +INFO[0001] Skipping unpacking as no commands require it. +INFO[0001] Taking snapshot of full filesystem... +INFO[0001] ENTRYPOINT ["/bin/bash", "-c", "echo hello"] +``` + +> Note: It is important to notice that the `destination` in the pod.yaml need to be replaced with your own. + +## Pull the image and test + +If as expected, the kaniko will build image and push to dockerhub successfully. Pull the image to local and run it to test: + +```shell +$ sudo docker run -it / +Unable to find image 'debuggy/helloworld:latest' locally +latest: Pulling from debuggy/helloworld +5667fdb72017: Pull complete +d83811f270d5: Pull complete +ee671aafb583: Pull complete +7fc152dfb3a6: Pull complete +Digest: sha256:2707d17754ea99ce0cf15d84a7282ae746a44ff90928c2064755ee3b35c1057b +Status: Downloaded newer image for debuggy/helloworld:latest +hello +``` + +Congratulation! You have gone through the hello world successfully, please refer to project for more details. diff --git a/examples/pod.yaml b/examples/pod.yaml new file mode 100644 index 0000000000..6b6692721e --- /dev/null +++ b/examples/pod.yaml @@ -0,0 +1,27 @@ +apiVersion: v1 +kind: Pod +metadata: + name: kaniko +spec: + containers: + - name: kaniko + image: gcr.io/kaniko-project/executor:latest + args: ["--dockerfile=/workspace/dockerfile", + "--context=dir://workspace", + "--destination=/"] # replace with your dockerhub account + volumeMounts: + - name: kaniko-secret + mountPath: /root + - name: dockerfile-storage + mountPath: /workspace + restartPolicy: Never + volumes: + - name: kaniko-secret + secret: + secretName: regcred + items: + - key: .dockerconfigjson + path: .docker/config.json + - name: dockerfile-storage + persistentVolumeClaim: + claimName: dockerfile-claim diff --git a/examples/volume-claim.yaml b/examples/volume-claim.yaml new file mode 100644 index 0000000000..7a1abbf05c --- /dev/null +++ b/examples/volume-claim.yaml @@ -0,0 +1,11 @@ +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: dockerfile-claim +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 8Gi + storageClassName: local-storage diff --git a/examples/volume.yaml b/examples/volume.yaml new file mode 100644 index 0000000000..9ff81d6c8b --- /dev/null +++ b/examples/volume.yaml @@ -0,0 +1,14 @@ +apiVersion: v1 +kind: PersistentVolume +metadata: + name: dockerfile + labels: + type: local +spec: + capacity: + storage: 10Gi + accessModes: + - ReadWriteOnce + storageClassName: local-storage + hostPath: + path: # replace with local directory, such as "/home//kaniko" \ No newline at end of file From a36d59046c15fbde62524c66d2ca29ffd4e228ae Mon Sep 17 00:00:00 2001 From: Mingliang Tao Date: Sun, 29 Sep 2019 21:32:19 +0800 Subject: [PATCH 2/2] Update tutorial context --- docs/tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 298690dff2..369450deca 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -6,7 +6,7 @@ This tutorial is for beginners who want to start using kaniko and aims to establ 1. [Prerequisities](#Prerequisities) 2. [Prepare config files for kaniko](#Prepare-config-files-for-kaniko) -3. [Prepare the mounted directory in minikube](#Prepare-the-mounted-directory-in-minikube) +3. [Prepare the local mounted directory](#Prepare-the-local-mounted-directory) 4. [Create a Secret that holds your authorization token](#Create-a-Secret-that-holds-your-authorization-token) 5. [Create resources in kubernetes](#Create-resources-in-kubernetes) 6. [Pull the image and test](#Pull-the-image-and-test) @@ -18,7 +18,7 @@ This tutorial is for beginners who want to start using kaniko and aims to establ ## Prepare config files for kaniko -After installing minikube, we should prepare several config files to create resources in kubernetes, which are: +Prepare several config files to create resources in kubernetes, which are: - [pod.yaml](../examples/pod.yaml) is for starting a kaniko container to build the example image. - [volume.yaml](../examples/volume.yaml) is for creating a persistent volume used as kaniko build context.