Skip to content
This repository was archived by the owner on Jun 3, 2025. It is now read-only.

Commit e87304d

Browse files
tejal29tejal29
authored
Merge pull request #790 from debuggy/tutorial
Add getting started tutorial
2 parents 865d49c + a36d590 commit e87304d

5 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ _If you are interested in contributing to kaniko, see [DEVELOPMENT.md](DEVELOPME
2121
- [How does kaniko work?](#how-does-kaniko-work)
2222
- [Known Issues](#known-issues)
2323
- [Demo](#demo)
24+
- [Tutorial](#tutorial)
2425
- [Using kaniko](#using-kaniko)
2526
- [kaniko Build Contexts](#kaniko-build-contexts)
2627
- [Running kaniko](#running-kaniko)
@@ -77,6 +78,10 @@ kaniko does not support building Windows containers.
7778

7879
![Demo](/docs/demo.gif)
7980

81+
## Tutorial
82+
83+
For a detailed example of kaniko with local storage, please refer to a [getting started tutorial](./docs/tutorial.md).
84+
8085
## Using kaniko
8186

8287
To use kaniko to build and push an image for you, you will need:

‎docs/tutorial.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Getting Started Tutorial
2+
3+
This tutorial is for beginners who want to start using kaniko and aims to establish a quick start test case.
4+
5+
## Table of Content
6+
7+
1. [Prerequisities](#Prerequisities)
8+
2. [Prepare config files for kaniko](#Prepare-config-files-for-kaniko)
9+
3. [Prepare the local mounted directory](#Prepare-the-local-mounted-directory)
10+
4. [Create a Secret that holds your authorization token](#Create-a-Secret-that-holds-your-authorization-token)
11+
5. [Create resources in kubernetes](#Create-resources-in-kubernetes)
12+
6. [Pull the image and test](#Pull-the-image-and-test)
13+
14+
## Prerequisities
15+
16+
- 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/).
17+
- A [dockerhub](https://hub.docker.com/) account to push built image public.
18+
19+
## Prepare config files for kaniko
20+
21+
Prepare several config files to create resources in kubernetes, which are:
22+
23+
- [pod.yaml](../examples/pod.yaml) is for starting a kaniko container to build the example image.
24+
- [volume.yaml](../examples/volume.yaml) is for creating a persistent volume used as kaniko build context.
25+
- [volume-claim.yaml](../examples/volume-claim.yaml) is for creating a persistent volume claim which will mounted in the kaniko container.
26+
27+
## Prepare the local mounted directory
28+
29+
SSH into the cluster, and create a local directory which will be mounted in kaniko container as build context. Create a simple dockerfile there.
30+
31+
> 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).
32+
33+
```shell
34+
$ mkdir kaniko && cd kaniko
35+
$ echo 'FROM ubuntu' >> dockerfile
36+
$ echo 'ENTRYPOINT ["/bin/bash", "-c", "echo hello"]' >> dockerfile
37+
$ cat dockerfile
38+
FROM ubuntu
39+
ENTRYPOINT ["/bin/bash", "-c", "echo hello"]
40+
$ pwd
41+
/home/<user-name>/kaniko # copy this path in volume.yaml file
42+
```
43+
44+
> Note: It is important to notice that the `hostPath` in the volume.yaml need to be replaced with the local directory you created.
45+
46+
## Create a Secret that holds your authorization token
47+
48+
A Kubernetes cluster uses the Secret of docker-registry type to authenticate with a docker registry to push an image.
49+
50+
Create this Secret, naming it regcred:
51+
52+
```shell
53+
kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
54+
```
55+
56+
- `<your-registry-server>` is your Private Docker Registry FQDN. (https://index.docker.io/v1/ for DockerHub)
57+
- `<your-name>` is your Docker username.
58+
- `<your-pword>` is your Docker password.
59+
- `<your-email>` is your Docker email.
60+
61+
This secret will be used in pod.yaml config.
62+
63+
## Create resources in kubernetes
64+
65+
```shell
66+
# create persistent volume
67+
$ kubectl create -f volume.yaml
68+
persistentvolume/dockerfile created
69+
70+
# create persistent volume claim
71+
$ kubectl create -f volume-claim.yaml
72+
persistentvolumeclaim/dockerfile-claim created
73+
74+
# check whether the volume mounted correctly
75+
$ kubectl get pv dockerfile
76+
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE
77+
dockerfile 10Gi RWO Retain Bound default/dockerfile-claim local-storage 1m
78+
79+
# create pod
80+
$ kubectl create -f pod.yaml
81+
pod/kaniko created
82+
$ kubectl get pods
83+
NAME READY STATUS RESTARTS AGE
84+
kaniko 0/1 ContainerCreating 0 7s
85+
86+
# check whether the build complete and show the build logs
87+
$ kubectl get pods
88+
NAME READY STATUS RESTARTS AGE
89+
kaniko 0/1 Completed 0 34s
90+
$ kubectl logs kaniko
91+
➜ kubectl logs kaniko
92+
INFO[0000] Resolved base name ubuntu to ubuntu
93+
INFO[0000] Resolved base name ubuntu to ubuntu
94+
INFO[0000] Downloading base image ubuntu
95+
INFO[0000] Error while retrieving image from cache: getting file info: stat /cache/sha256:1bbdea4846231d91cce6c7ff3907d26fca444fd6b7e3c282b90c7fe4251f9f86: no such file or directory
96+
INFO[0000] Downloading base image ubuntu
97+
INFO[0001] Built cross stage deps: map[]
98+
INFO[0001] Downloading base image ubuntu
99+
INFO[0001] Error while retrieving image from cache: getting file info: stat /cache/sha256:1bbdea4846231d91cce6c7ff3907d26fca444fd6b7e3c282b90c7fe4251f9f86: no such file or directory
100+
INFO[0001] Downloading base image ubuntu
101+
INFO[0001] Skipping unpacking as no commands require it.
102+
INFO[0001] Taking snapshot of full filesystem...
103+
INFO[0001] ENTRYPOINT ["/bin/bash", "-c", "echo hello"]
104+
```
105+
106+
> Note: It is important to notice that the `destination` in the pod.yaml need to be replaced with your own.
107+
108+
## Pull the image and test
109+
110+
If as expected, the kaniko will build image and push to dockerhub successfully. Pull the image to local and run it to test:
111+
112+
```shell
113+
$ sudo docker run -it <user-name>/<repo-name>
114+
Unable to find image 'debuggy/helloworld:latest' locally
115+
latest: Pulling from debuggy/helloworld
116+
5667fdb72017: Pull complete
117+
d83811f270d5: Pull complete
118+
ee671aafb583: Pull complete
119+
7fc152dfb3a6: Pull complete
120+
Digest: sha256:2707d17754ea99ce0cf15d84a7282ae746a44ff90928c2064755ee3b35c1057b
121+
Status: Downloaded newer image for debuggy/helloworld:latest
122+
hello
123+
```
124+
125+
Congratulation! You have gone through the hello world successfully, please refer to project for more details.

‎examples/pod.yaml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
apiVersion: v1
2+
kind: Pod
3+
metadata:
4+
name: kaniko
5+
spec:
6+
containers:
7+
- name: kaniko
8+
image: gcr.io/kaniko-project/executor:latest
9+
args: ["--dockerfile=/workspace/dockerfile",
10+
"--context=dir://workspace",
11+
"--destination=<user-name>/<repo>"] # replace with your dockerhub account
12+
volumeMounts:
13+
- name: kaniko-secret
14+
mountPath: /root
15+
- name: dockerfile-storage
16+
mountPath: /workspace
17+
restartPolicy: Never
18+
volumes:
19+
- name: kaniko-secret
20+
secret:
21+
secretName: regcred
22+
items:
23+
- key: .dockerconfigjson
24+
path: .docker/config.json
25+
- name: dockerfile-storage
26+
persistentVolumeClaim:
27+
claimName: dockerfile-claim

‎examples/volume-claim.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
kind: PersistentVolumeClaim
2+
apiVersion: v1
3+
metadata:
4+
name: dockerfile-claim
5+
spec:
6+
accessModes:
7+
- ReadWriteOnce
8+
resources:
9+
requests:
10+
storage: 8Gi
11+
storageClassName: local-storage

‎examples/volume.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
apiVersion: v1
2+
kind: PersistentVolume
3+
metadata:
4+
name: dockerfile
5+
labels:
6+
type: local
7+
spec:
8+
capacity:
9+
storage: 10Gi
10+
accessModes:
11+
- ReadWriteOnce
12+
storageClassName: local-storage
13+
hostPath:
14+
path: <local-directory> # replace with local directory, such as "/home/<user-name>/kaniko"

0 commit comments

Comments
 (0)