From 77c7980a7485374442f85297c94fa756a9360461 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Tue, 29 Nov 2016 12:21:55 -0500 Subject: [PATCH 01/13] New page for reviewing issues process adds a new page to the contribute section and navigation that describes the reviewing and labeling process for backlog/newly created issues --- _data/support.yml | 2 + docs/contribute/review-issues.md | 65 ++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 docs/contribute/review-issues.md diff --git a/_data/support.yml b/_data/support.yml index 1b8e80699a..132a1013c3 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -14,6 +14,8 @@ toc: path: /docs/contribute/stage-documentation-changes/ - title: Using Page Templates path: /docs/contribute/page-templates/ + - title: Reviewing Documentation Issues + path: /docs/contribute/review-issues/ - title: Documentation Style Guide path: /docs/contribute/style-guide/ diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md new file mode 100644 index 0000000000..c74404a08e --- /dev/null +++ b/docs/contribute/review-issues.md @@ -0,0 +1,65 @@ +--- +--- + +{% capture overview %} + +This page explains how you should review and prioritize documentation issues made for the [kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} repository. The purpose is to provide a way to organize issues and make it easier to contribute to Kubernetes documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues. +{% endcapture %} + +{% capture body %} + +## Categorizing issues +Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed. + + +#### Actionable +* Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear) +* Allows contributors to have easy to find issues to work on + + +#### Tech Review Needed +* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a SME needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant) +* Promotes transparency about level of work needed for the issue and that issue is in progress + +#### Docs Review Needed +* Issues that are suggestions for better processes or site improvements that require community agreement to be implemented +* Topics can be brought to SIG meetings as agenda items + + +## Prioritizing Issues +The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change. + +#### P1 +* Major content errors affecting more than 1 page +* Broken code sample on a heavily trafficked page +* Errors on a “getting started” page +* Well known or highly publicized customer pain points +* Automation issues + +#### P2 +* Default for all new issues +* Broken code for sample that is not heavily used +* Minor content issues in a heavily trafficked page +* Major content issues on a lower-trafficked page + +#### P3 +* Typos and broken anchor links + +## Handling special issue types + +### Duplicate issues + +### Dead link issues +Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3. + +{% endcapture %} + + + +{% capture whatsnext %} +* Learn about [writing a new topic](/docs/contribute/write-new-topic). +* Learn about [using page templates](/docs/contribute/page-templates/). +* Learn about [staging your changes](/docs/contribute/stage-documentation-changes). +{% endcapture %} + +{% include templates/concept.md %} From 18252f80e453265ab491ba1664dbdcadbece8b2f Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Tue, 29 Nov 2016 12:33:35 -0500 Subject: [PATCH 02/13] adding in duplicate seciton which was weirdly left out adding in left out section --- docs/contribute/review-issues.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index c74404a08e..58a72f6697 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -48,6 +48,7 @@ The following labels and definitions should be used to prioritize issues. If you ## Handling special issue types ### Duplicate issues +If a single problem has one or more issues open for it, the problem should be consolodated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem. ### Dead link issues Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3. From 4ed6b4e6f462955ad07457cbe030eb372070650c Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Fri, 9 Dec 2016 14:15:28 -0500 Subject: [PATCH 03/13] Fixed whats next section in TOC and SME --- docs/contribute/review-issues.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index 58a72f6697..51de679064 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -8,7 +8,7 @@ This page explains how you should review and prioritize documentation issues mad {% capture body %} -## Categorizing issues +### Categorizing issues Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed. @@ -18,7 +18,7 @@ Issues should be sorted into different buckets of work using the following label #### Tech Review Needed -* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a SME needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant) +* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant) * Promotes transparency about level of work needed for the issue and that issue is in progress #### Docs Review Needed @@ -26,7 +26,7 @@ Issues should be sorted into different buckets of work using the following label * Topics can be brought to SIG meetings as agenda items -## Prioritizing Issues +### Prioritizing Issues The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change. #### P1 @@ -45,12 +45,12 @@ The following labels and definitions should be used to prioritize issues. If you #### P3 * Typos and broken anchor links -## Handling special issue types +### Handling special issue types -### Duplicate issues +#### Duplicate issues If a single problem has one or more issues open for it, the problem should be consolodated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem. -### Dead link issues +#### Dead link issues Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3. {% endcapture %} From add6e30826bf907a129650bd292ae313f8645e50 Mon Sep 17 00:00:00 2001 From: mark007 Date: Wed, 4 Jan 2017 14:58:58 +0000 Subject: [PATCH 04/13] Update index.html --- docs/tutorials/kubernetes-basics/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/kubernetes-basics/index.html b/docs/tutorials/kubernetes-basics/index.html index eac6d89492..5fc4b5b9bb 100644 --- a/docs/tutorials/kubernetes-basics/index.html +++ b/docs/tutorials/kubernetes-basics/index.html @@ -34,7 +34,7 @@ title: Overview

What can Kubernetes do for you?

-

With modern web services, users expect applications to be available 24/7, and developers expect to deploy new versions of those applications several times a day. Containerization helps package software to serve these goals, enabling applications to be released and updated in an easy and fast way without downtime. Kubernetes helps you make sure those containerized applications run where and when you want, and helps them find the resources and tools they need to work. Kubernetes is a production-ready, open source platform designed with the Google's accumulated experience in container orchestration, combined with best-of-breed ideas from the community.

+

With modern web services, users expect applications to be available 24/7, and developers expect to deploy new versions of those applications several times a day. Containerization helps package software to serve these goals, enabling applications to be released and updated in an easy and fast way without downtime. Kubernetes helps you make sure those containerized applications run where and when you want, and helps them find the resources and tools they need to work. Kubernetes is a production-ready, open source platform designed with Google's accumulated experience in container orchestration, combined with best-of-breed ideas from the community.

From 52ec922685c22d93c82efb9969fca51d465f5dd8 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Wed, 4 Jan 2017 08:56:49 -0800 Subject: [PATCH 05/13] deprecation policy bug: at X+9 we remove v1 --- docs/deprecation-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index d349e6c0b9..c51326bbc5 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -161,7 +161,7 @@ versions are supported in a series of subsequent releases. X+9 - v1, v2 + v2
  • v1 is removed, "action required" relnote
    • From e8b5af42028303c84cdfd7042e738353c02208f3 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Thu, 29 Dec 2016 16:32:23 -0800 Subject: [PATCH 06/13] Fix incorrect / obsolete references to RCs and files --- docs/user-guide/connecting-applications.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/user-guide/connecting-applications.md b/docs/user-guide/connecting-applications.md index adc47a64b4..f10cb25e4b 100644 --- a/docs/user-guide/connecting-applications.md +++ b/docs/user-guide/connecting-applications.md @@ -174,7 +174,7 @@ You can acquire all these from the [nginx https example](https://github.com/kube ```shell $ make keys secret KEY=/tmp/nginx.key CERT=/tmp/nginx.crt SECRET=/tmp/secret.json $ kubectl create -f /tmp/secret.json -secrets/nginxsecret +secret "nginxsecret" created $ kubectl get secrets NAME TYPE DATA default-token-il9rc kubernetes.io/service-account-token 1 @@ -183,19 +183,16 @@ nginxsecret Opaque 2 Now modify your nginx replicas to start an https server using the certificate in the secret, and the Service, to expose both ports (80 and 443): -{% include code.html language="yaml" file="nginx-secure-app.yaml" ghlink="/docs/user-guide/nginx-secure-app" %} +{% include code.html language="yaml" file="nginx-secure-app.yaml" ghlink="/docs/user-guide/nginx-secure-app.yaml" %} Noteworthy points about the nginx-secure-app manifest: -- It contains both rc and service specification in the same file +- It contains both Deployment and Service specification in the same file - The [nginx server](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/https-nginx/default.conf) serves http traffic on port 80 and https traffic on 443, and nginx Service exposes both ports. - Each container has access to the keys through a volume mounted at /etc/nginx/ssl. This is setup *before* the nginx server is started. ```shell -$ kubectl apply -f ./nginx-secure-app.yaml -$ kubectl delete rc,svc -l app=nginx; kubectl create -f ./nginx-app.yaml -service "my-nginx" configured -deployment "my-nginx" configured +$ kubectl delete deployments,svc my-nginx; kubectl create -f ./nginx-secure-app.yaml ``` At this point you can reach the nginx server from any node. @@ -216,11 +213,10 @@ Lets test this from a pod (the same secret is being reused for simplicity, the p ```shell $ kubectl create -f ./curlpod.yaml -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -curlpod 1/1 Running 0 2m - -$ kubectl exec curlpod -- curl https://my-nginx --cacert /etc/nginx/ssl/nginx.crt +$ kubectl get pods -l app=curlpod +NAME READY STATUS RESTARTS AGE +curl-deployment-1515033274-1410r 1/1 Running 0 1m +$ kubectl exec curl-deployment-1515033274-1410r -- curl https://my-nginx --cacert /etc/nginx/ssl/nginx.crt ... Welcome to nginx! ... @@ -291,6 +287,7 @@ $ kubectl describe service my-nginx LoadBalancer Ingress: a320587ffd19711e5a37606cf4a74574-1142138393.us-east-1.elb.amazonaws.com ... ``` + ## Further reading Kubernetes also supports Federated Services, which can span multiple From 59ede5a392cd9eb5964be341c9c29dc1eeaeec76 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Wed, 4 Jan 2017 16:12:21 -0500 Subject: [PATCH 07/13] Correcting file name in support toc --- _data/support.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/support.yml b/_data/support.yml index eabd584e33..a79aa7addb 100644 --- a/_data/support.yml +++ b/_data/support.yml @@ -10,7 +10,7 @@ toc: - docs/contribute/write-new-topic.md - docs/contribute/stage-documentation-changes.md - docs/contribute/page-templates.md - - docs/contribute/review-issues/ + - docs/contribute/review-issues.md - docs/contribute/style-guide.md From 267b1e25d2132a11db2888ba81e1187ccca89417 Mon Sep 17 00:00:00 2001 From: a-mccarthy Date: Wed, 4 Jan 2017 16:13:23 -0500 Subject: [PATCH 08/13] Adding page title --- docs/contribute/review-issues.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contribute/review-issues.md b/docs/contribute/review-issues.md index 51de679064..476591e1da 100644 --- a/docs/contribute/review-issues.md +++ b/docs/contribute/review-issues.md @@ -1,4 +1,5 @@ --- +title: Reviewing Documentation Issues --- {% capture overview %} From 6500a19d2fd631f2647b1eef0eaa5e5283d1eacf Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 27 Dec 2016 13:04:10 -0800 Subject: [PATCH 09/13] Write new Task: Pulling an Image from a Private Registry --- _data/tasks.yml | 1 + .../private-reg-pod.yaml | 11 ++ .../pull-image-private-registry.md | 133 ++++++++++++++++++ 3 files changed, 145 insertions(+) create mode 100644 docs/tasks/configure-pod-container/private-reg-pod.yaml create mode 100644 docs/tasks/configure-pod-container/pull-image-private-registry.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 05a880637a..7937b2f0d3 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -10,6 +10,7 @@ toc: - docs/tasks/configure-pod-container/assign-cpu-ram-container.md - docs/tasks/configure-pod-container/configure-volume-storage.md - docs/tasks/configure-pod-container/distribute-credentials-secure.md + - docs/tasks/configure-pod-container/pull-image-private-registry.md - title: Accessing Applications in a Cluster section: diff --git a/docs/tasks/configure-pod-container/private-reg-pod.yaml b/docs/tasks/configure-pod-container/private-reg-pod.yaml new file mode 100644 index 0000000000..9928b6d608 --- /dev/null +++ b/docs/tasks/configure-pod-container/private-reg-pod.yaml @@ -0,0 +1,11 @@ +apiVersion: v1 +kind: Pod +metadata: + name: private-reg +spec: + containers: + - name: private-reg-container + image: + imagePullSecrets: + - name: regsecret + diff --git a/docs/tasks/configure-pod-container/pull-image-private-registry.md b/docs/tasks/configure-pod-container/pull-image-private-registry.md new file mode 100644 index 0000000000..5560dd9a30 --- /dev/null +++ b/docs/tasks/configure-pod-container/pull-image-private-registry.md @@ -0,0 +1,133 @@ +--- +title: Pulling an Image from a Private Registry +--- + +{% capture overview %} + +This page shows how to create a Pod that uses a Secret to pull an image from a +private Docker registry or repository. + +{% endcapture %} + +{% capture prerequisites %} + +* {% include task-tutorial-prereqs.md %} + +* To do this exercise, you need a +[Docker ID](https://docs.docker.com/docker-id/) and password. + +{% endcapture %} + +{% capture steps %} + +### Logging in to Docker + + docker login + +When prompted, enter your Docker username and password. + +The login process creates or updates a `config.json` file that holds an +authorization token. + +View the `configfile.json` file: + + cat ~/.docker/config.json + +The output contains a section similar to this: + + { + "auths": { + "https://index.docker.io/v1/": { + "auth": "c3RldmU1MzpTdGV2ZURvY2tAIzE2" + } + } + } + +### Creating a Secret that holds your authorization token + +Create a Secret named `regsecret`: + + kubectl create secret docker-registry regsecret --docker-username= --docker-password= --docker-email= + +where: + +* `` is your Docker username. +* `` is your Docker password. +* `` is your Docker email. + +### Understanding your Secret + +To understand what's in the Secret you just created, start by viewing the +Secret in YAML format: + + kubectl get secret regsecret --output=yaml + +The output is similar to this: + + apiVersion: v1 + data: + .dockercfg: eyJodHRwczovL2luZGV4L ... J0QUl6RTIifX0= + kind: Secret + metadata: + ... + name: regsecret + ... + type: kubernetes.io/dockercfg + +The value of the `.dockercfg` field is a base64 representation of your secret data. + +Copy the base64 representation of the secret data into a file named `secret64`. + +**Important**: Make sure there are no line breaks in your `secret64` file. + +To understand what is in the `dockercfg` field, convert the secret data to a +readable format: + + base64 -d secret64 + +The output is similar to this: + + {"https://index.docker.io/v1/":{"username":"janedoe","password":"xxxxxxxxxxx","email":"jdoe@example.com","auth":"c3RldmU1MzpTdGV2ZURvY2tAIzE2"}} + +Notice that the secret data contains the authorization token from your +`config.json` file. + +### Creating a Pod that uses your Secret + +Here is a configuration file for a Pod that needs access to your secret data: + +{% include code.html language="yaml" file="private-reg-pod.yaml" ghlink="/docs/tasks/configure-pod-container/private-reg-pod.yaml" %} + +Copy the contents of `private-reg-pod.yaml` to your own file named +`my-private-reg-pod.yaml`. In your file, replace `` with +the path to an image in a private repository. + +Example Docker Hub private image: + + janedoe/jdoe-private:v1 + +To pull the image from the private repository, Kubernetes needs credentials. The + `imagePullSecrets` field in the configuration file specifies that Kubernetes + should get the credentials from a Secret named +`regsecret`. + +Create a Pod that uses your Secret, and verify that the Pod is running: + + kubectl create -f my-private-reg-pod.yaml + kubectl get pod private-reg + +{% endcapture %} + +{% capture whatsnext %} + +* Learn more about [Secrets](/docs/user-guide/secrets/). +* Learn more about +[using a private registry](/docs/user-guide/images/#using-a-private-registry). +* See [kubectl create secret docker-registry](/docs/user-guide/kubectl/kubectl_create_secret_docker-registry/). +* See [Secret](/docs/api-reference/v1/definitions/#_v1_secret) +* See the `imagePullSecrets` field of +[PodSpec](/docs/api-reference/v1/definitions/#_v1_podspec). + +{% endcapture %} + +{% include templates/task.md %} From 1e0566780532a333d7b3c15d77cc5d1be04819da Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Fri, 30 Dec 2016 03:47:49 -0800 Subject: [PATCH 10/13] Write new Task: Configuring Liveness and Readiness Probes Addressed reviewer comments. Addressed more reviewer comments. Fix broken link. --- _data/tasks.yml | 1 + .../configure-liveness-readiness-probes.md | 271 ++++++++++++++++++ .../exec-liveness.yaml | 26 ++ .../http-liveness.yaml | 25 ++ docs/user-guide/liveness/index.md | 78 ----- 5 files changed, 323 insertions(+), 78 deletions(-) create mode 100644 docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md create mode 100644 docs/tasks/configure-pod-container/exec-liveness.yaml create mode 100644 docs/tasks/configure-pod-container/http-liveness.yaml delete mode 100644 docs/user-guide/liveness/index.md diff --git a/_data/tasks.yml b/_data/tasks.yml index 7937b2f0d3..7b6433c5f8 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -11,6 +11,7 @@ toc: - docs/tasks/configure-pod-container/configure-volume-storage.md - docs/tasks/configure-pod-container/distribute-credentials-secure.md - docs/tasks/configure-pod-container/pull-image-private-registry.md + - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md - title: Accessing Applications in a Cluster section: diff --git a/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md b/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md new file mode 100644 index 0000000000..3b7f7462ef --- /dev/null +++ b/docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md @@ -0,0 +1,271 @@ +--- +redirect_from: +- "/docs/user-guide/liveness/" +- "/docs/user-guide.liveness.html" +title: Configuring Liveness and Readiness Probes +--- + +{% capture overview %} + +This page shows how to configure liveness and readiness probes for Containers. + +The [kubelet](/docs/admin/kubelet/) uses liveness probes to know when to +restart a Container. For example, liveness probes could catch a deadlock, +where an application is running, but unable to make progress. Restarting a +Container in such a state can help to make the application more available +despite bugs. + +The kubelet uses readiness probes to know when a Container is ready to start +accepting traffic. A Pod is considered ready when all of its Containers are ready. +One use of this signal is to control which Pods are used as backends for Services. +When a Pod is not ready, it is removed from Service load balancers. + +{% endcapture %} + +{% capture prerequisites %} + +{% include task-tutorial-prereqs.md %} + +{% endcapture %} + +{% capture steps %} + +### Defining a liveness command + +Many applications running for long periods of time eventually transition to +broken states, and cannot recover except by being restarted. Kubernetes provides +liveness probes to detect and remedy such situations. + +In this exercise, you create a Pod that runs a Container based on the +`gcr.io/google_containers/busybox` image. Here is the configuration file for the Pod: + +{% include code.html language="yaml" file="exec-liveness.yaml" ghlink="/docs/tasks/configure-pod-container/exec-liveness.yaml" %} + +In the configuration file, you can see that the Pod has a single Container. +The `livenessProbe` field specifies that the kubelet should perform a liveness +probe every 5 seconds. The `initialDelaySeconds` field tells the kubelet that it +should wait 5 second before performing the first probe. To perform a probe, the +kubelet executes the command `cat /tmp/healthy` in the Container. If the +command succeeds, it returns 0, and the kubelet considers the Container to be alive and +healthy. If the command returns a non-zero value, the kubelet kills the Container +and restarts it. + +When the Container starts, it executes this command: + +```shell +/bin/sh -c "touch /tmp/healthy; sleep 30; rm -rf /tmp/healthy; sleep 600" +``` + +For the first 30 seconds of the Container's life, there is a `/tmp/healthy` file. +So during the first 30 seconds, the command `cat /tmp/healthy` returns a success +code. After 30 seconds, `cat /tmp/healthy` returns a failure code. + +Create the Pod: + +```shell +kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/exec-liveness.yaml +``` + +Within 30 seconds, view the Pod events: + +``` +kubectl describe pod liveness-exec +``` + +The output indicates that no liveness probes have failed yet: + +```shell +FirstSeen LastSeen Count From SubobjectPath Type Reason Message +--------- -------- ----- ---- ------------- -------- ------ ------- +24s 24s 1 {default-scheduler } Normal Scheduled Successfully assigned liveness-exec to worker0 +23s 23s 1 {kubelet worker0} spec.containers{liveness} Normal Pulling pulling image "gcr.io/google_containers/busybox" +23s 23s 1 {kubelet worker0} spec.containers{liveness} Normal Pulled Successfully pulled image "gcr.io/google_containers/busybox" +23s 23s 1 {kubelet worker0} spec.containers{liveness} Normal Created Created container with docker id 86849c15382e; Security:[seccomp=unconfined] +23s 23s 1 {kubelet worker0} spec.containers{liveness} Normal Started Started container with docker id 86849c15382e +``` + +After 30 seconds, view the Pod events again: + +```shell +kubectl describe pod liveness-exec +``` + +At the bottom of the output, there are messages indicating that the liveness +probes have failed, and the containers have been killed and recreated. + +```shell +FirstSeen LastSeen Count From SubobjectPath Type Reason Message +--------- -------- ----- ---- ------------- -------- ------ ------- +37s 37s 1 {default-scheduler } Normal Scheduled Successfully assigned liveness-exec to worker0 +36s 36s 1 {kubelet worker0} spec.containers{liveness} Normal Pulling pulling image "gcr.io/google_containers/busybox" +36s 36s 1 {kubelet worker0} spec.containers{liveness} Normal Pulled Successfully pulled image "gcr.io/google_containers/busybox" +36s 36s 1 {kubelet worker0} spec.containers{liveness} Normal Created Created container with docker id 86849c15382e; Security:[seccomp=unconfined] +36s 36s 1 {kubelet worker0} spec.containers{liveness} Normal Started Started container with docker id 86849c15382e +2s 2s 1 {kubelet worker0} spec.containers{liveness} Warning Unhealthy Liveness probe failed: cat: can't open '/tmp/healthy': No such file or directory +``` + +Wait another 30 seconds, and verify that the Container has been restarted: + +```shell +kubectl get pod liveness-exec +``` + +The output shows that `RESTARTS` has been incremented: + +```shell +NAME READY STATUS RESTARTS AGE +liveness-exec 1/1 Running 1 1m +``` + +### Defining a liveness HTTP request + +Another kind of liveness probe uses an HTTP GET request. Here is the configuration +file for a Pod that runs a container based on the `gcr.io/google_containers/liveness` +image. + +{% include code.html language="yaml" file="http-liveness.yaml" ghlink="/docs/tasks/configure-pod-container/http-liveness.yaml" %} + +In the configuration file, you can see that the Pod has a single Container. +The `livenessProbe` field specifies that the kubelet should perform a liveness +probe every 3 seconds. The `initialDelaySeconds` field tells the kubelet that it +should wait 3 seconds before performing the first probe. To perform a probe, the +kubelet sends an HTTP GET request to the server that is running in the Container +and listening on port 8080. If the handler for the server's `/healthz` path +returns a success code, the kubelet considers the Container to be alive and +healthy. If the handler returns a failure code, the kubelet kills the Container +and restarts it. + +Any code greater than or equal to 200 and less than 400 indicates success. Any +other code indicates failure. + +You can see the source code for the server in +[server.go](http://k8s.io/docs/user-guide/liveness/image/server.go). + +For the first 10 seconds that the Container is alive, the `/healthz` handler +returns a status of 200. After that, the handler returns a status of 500. + +```go +http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { + duration := time.Now().Sub(started) + if duration.Seconds() > 10 { + w.WriteHeader(500) + w.Write([]byte(fmt.Sprintf("error: %v", duration.Seconds()))) + } else { + w.WriteHeader(200) + w.Write([]byte("ok")) + } +``` + +The kubelet starts performing health checks 3 seconds after the Container starts. +So the first couple of health checks will succeed. But after 10 seconds, the health +checks will fail, and the kubelet will kill and restart the Container. + +To try the HTTP liveness check, create a Pod: + +```shell +kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/http-liveness.yaml +``` + +After 10 seconds, view Pod events to verify that liveness probes have failed and +the Container has been restarted: + +```shell +kubectl describe pod liveness-http +``` + +### Using a named port + +You can use a named +[ContainerPort](/docs/api-reference/v1/definitions/#_v1_containerport) +for HTTP liveness checks: + +```yaml +ports: +- name: liveness-port + containerPort: 8080 + hostPort: 8080 + +livenessProbe: + httpGet: + path: /healthz + port: liveness-port +``` + +### Defining readiness probes + +Sometimes, applications are temporarily unable to serve traffic. +For example, an application might need to load large data or configuration +files during startup. In such cases, you don't want to kill the application, +but you don’t want to send it requests either. Kubernetes provides +readiness probes to detect and mitigate these situations. A pod with containers +reporting that they are not ready does not receive traffic through Kubernetes +Services. + +Readiness probes are configured similarly to liveness probes. The only difference +is that you use the `readinessProbe` field instead of the `livenessProbe` field. + +```yaml +readinessProbe: + exec: + command: + - cat + - /tmp/healthy + initialDelaySeconds: 5 + periodSeconds: 5 +``` + +{% endcapture %} + + +{% capture discussion %} + +### Discussion + +{% comment %} +Eventually, some of this Discussion section could be moved to a concept topic. +{% endcomment %} + +[Probes](/docs/api-reference/v1/definitions/#_v1_probe) have these additional fields that you can use to more precisely control the behavior of liveness and readiness checks: + +* timeoutSeconds +* successThreshold +* failureThreshold + +[HTTP probes](/docs/api-reference/v1/definitions/#_v1_httpgetaction) +have these additional fields: + +* host +* scheme +* httpHeaders + +For an HTTP probe, the kubelet sends an HTTP request to the specified path and +port to perform the check. The kubelet sends the probe to the container’s IP address, +unless the address is overridden by the optional `host` field in `httpGet`. +In most scenarios, you do not want to set the `host` field. Here's one scenario +where you would set it. Suppose the Container listens on 127.0.0.1 and the Pod's +`hostNetwork` field is true. Then `host`, under `httpGet`, should be set to 127.0.0.1. +If your pod relies on virtual hosts, which is probably the more common case, +you should not use `host`, but rather set the `Host` header in `httpHeaders`. + +In addition to command probes and HTTP probes, Kubenetes supports +[TCP probes](/docs/api-reference/v1/definitions/#_v1_tcpsocketaction). + +{% endcapture %} + +{% capture whatsnext %} + +* Learn more about +[Container Probes](/docs/user-guide/pod-states/#container-probes). + +* Learn more about +[Health Checking section](/docs/user-guide/walkthrough/k8s201/#health-checking). + +#### Reference + +* [Pod](http://kubernetes.io/docs/api-reference/v1/definitions#_v1_pod) +* [Container](/docs/api-reference/v1/definitions/#_v1_container) +* [Probe](/docs/api-reference/v1/definitions/#_v1_probe) + +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tasks/configure-pod-container/exec-liveness.yaml b/docs/tasks/configure-pod-container/exec-liveness.yaml new file mode 100644 index 0000000000..7b04a5eb8d --- /dev/null +++ b/docs/tasks/configure-pod-container/exec-liveness.yaml @@ -0,0 +1,26 @@ +apiVersion: v1 +kind: Pod + +metadata: + labels: + test: liveness + name: liveness-exec +spec: + containers: + + - name: liveness + + args: + - /bin/sh + - -c + - touch /tmp/healthy; sleep 30; rm -rf /tmp/healthy; sleep 600 + + image: gcr.io/google_containers/busybox + + livenessProbe: + exec: + command: + - cat + - /tmp/healthy + initialDelaySeconds: 5 + periodSeconds: 5 diff --git a/docs/tasks/configure-pod-container/http-liveness.yaml b/docs/tasks/configure-pod-container/http-liveness.yaml new file mode 100644 index 0000000000..8485e3444e --- /dev/null +++ b/docs/tasks/configure-pod-container/http-liveness.yaml @@ -0,0 +1,25 @@ +apiVersion: v1 +kind: Pod +metadata: + labels: + test: liveness + name: liveness-http +spec: + containers: + + - name: liveness + + args: + - /server + + image: gcr.io/google_containers/liveness + + livenessProbe: + httpGet: + path: /healthz + port: 8080 + httpHeaders: + - name: X-Custom-Header + value: Awesome + initialDelaySeconds: 3 + periodSeconds: 3 diff --git a/docs/user-guide/liveness/index.md b/docs/user-guide/liveness/index.md deleted file mode 100644 index 5e77f07768..0000000000 --- a/docs/user-guide/liveness/index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -assignees: -- mikedanese -- thockin -title: Checking Pod Health ---- - -This example shows two types of pod [health checks](/docs/user-guide/production-pods/#liveness-and-readiness-probes-aka-health-checks): HTTP checks and container execution checks. - -The [exec-liveness.yaml](/docs/user-guide/liveness/exec-liveness.yaml) demonstrates the container execution check. - -{% include code.html language="yaml" file="exec-liveness.yaml" ghlink="/docs/user-guide/liveness/exec-liveness.yaml" %} - -Kubelet executes the command `cat /tmp/health` in the container and reports failure if the command returns a non-zero exit code. - -Note that the container removes the `/tmp/health` file after 10 seconds, - -```shell -echo ok > /tmp/health; sleep 10; rm -rf /tmp/health; sleep 600 -``` - -so when Kubelet executes the health check 15 seconds (defined by initialDelaySeconds) after the container started, the check would fail. - - -The [http-liveness.yaml](/docs/user-guide/liveness/http-liveness.yaml) demonstrates the HTTP check. -{% include code.html language="yaml" file="http-liveness.yaml" ghlink="/docs/user-guide/liveness/http-liveness.yaml" %} - - -The Kubelet sends an HTTP request to the specified path and port to perform the health check. If you take a look at image/server.go, you will see the server starts to respond with an error code 500 after 10 seconds, so the check fails. The Kubelet sends probes to the container's IP address, unless overridden by the optional `host` field in httpGet. If the container listens on `127.0.0.1` and `hostNetwork` is `true` (i.e., it does not use the pod-specific network), then `host` should be specified as `127.0.0.1`. Be warned that, outside of less common cases like that, `host` does probably not result in what you would expect. If you set it to a non-existing hostname (or your competitor's!), probes will never reach the pod, defeating the whole point of health checks. If your pod relies on e.g. virtual hosts, which is probably the more common case, you should not use `host`, but rather set the `Host` header in `httpHeaders`. - -### Using a named port for liveness probes - -You can also use a named `ContainerPort` for HTTP liveness checks. - -The [http-liveness-named-port.yaml](/docs/user-guide/liveness/http-liveness-named-port.yaml) demonstrates the named-port HTTP check. -{% include code.html language="yaml" file="http-liveness-named-port.yaml" ghlink="/docs/user-guide/liveness/http-liveness-named-port.yaml" %} - -This [guide](/docs/user-guide/walkthrough/k8s201/#health-checking) has more information on health checks. - -## Get your hands dirty - -To show the health check is actually working, first create the pods: - -```shell -$ kubectl create -f docs/user-guide/liveness/exec-liveness.yaml -$ kubectl create -f docs/user-guide/liveness/http-liveness.yaml -``` - -Check the status of the pods once they are created: - -```shell -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -[...] -liveness-exec 1/1 Running 0 13s -liveness-http 1/1 Running 0 13s -``` - -Check the status half a minute later, you will see the container restart count being incremented: - -```shell -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -[...] -liveness-exec 1/1 Running 1 36s -liveness-http 1/1 Running 1 36s -``` - -At the bottom of the *kubectl describe* output there are messages indicating that the liveness probes have failed, and the containers have been killed and recreated. - -```shell -$ kubectl describe pods liveness-exec -[...] -Sat, 27 Jun 2015 13:43:03 +0200 Sat, 27 Jun 2015 13:44:34 +0200 4 {kubelet kubernetes-node-6fbi} spec.containers{liveness} unhealthy Liveness probe failed: cat: can't open '/tmp/health': No such file or directory -Sat, 27 Jun 2015 13:44:44 +0200 Sat, 27 Jun 2015 13:44:44 +0200 1 {kubelet kubernetes-node-6fbi} spec.containers{liveness} killing Killing with docker id 65b52d62c635 -Sat, 27 Jun 2015 13:44:44 +0200 Sat, 27 Jun 2015 13:44:44 +0200 1 {kubelet kubernetes-node-6fbi} spec.containers{liveness} created Created with docker id ed6bb004ee10 -Sat, 27 Jun 2015 13:44:44 +0200 Sat, 27 Jun 2015 13:44:44 +0200 1 {kubelet kubernetes-node-6fbi} spec.containers{liveness} started Started with docker id ed6bb004ee10 -``` From 757dd707b6c47481ae21ec119cfb6b33ff49139a Mon Sep 17 00:00:00 2001 From: Oleg Shalygin Date: Wed, 4 Jan 2017 16:23:20 -0800 Subject: [PATCH 11/13] Update configs with username followed by password The way that the document currently flows and how we typically perceive credentials, we usually set our username first followed by the password. Seeing the configuration first set password then username seems counter-intuitive. There is nothing wrong with the docs, it is just clearer to view username=>password. --- docs/user-guide/secrets/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index 63a2a052ea..07764434fd 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -113,8 +113,8 @@ metadata: name: mysecret type: Opaque data: - password: MWYyZDFlMmU2N2Rm username: YWRtaW4= + password: MWYyZDFlMmU2N2Rm ``` The data field is a map. Its keys must match @@ -142,8 +142,8 @@ Get back the secret created in the previous section: $ kubectl get secret mysecret -o yaml apiVersion: v1 data: - password: MWYyZDFlMmU2N2Rm username: YWRtaW4= + password: MWYyZDFlMmU2N2Rm kind: Secret metadata: creationTimestamp: 2016-01-22T18:41:56Z From 3b3adcdd1e537e5fe8f32f7b526f089037add05a Mon Sep 17 00:00:00 2001 From: Mike Danese Date: Wed, 4 Jan 2017 20:32:41 -0800 Subject: [PATCH 12/13] temporary access to webmaster tools --- googlead862a0628bec321.html | 1 + 1 file changed, 1 insertion(+) create mode 100644 googlead862a0628bec321.html diff --git a/googlead862a0628bec321.html b/googlead862a0628bec321.html new file mode 100644 index 0000000000..00bd6e6c1a --- /dev/null +++ b/googlead862a0628bec321.html @@ -0,0 +1 @@ +google-site-verification: googlead862a0628bec321.html \ No newline at end of file From 353bfcfd8484fd6b761f298f387a3bea18682e97 Mon Sep 17 00:00:00 2001 From: Charlie Drage Date: Thu, 5 Jan 2017 08:57:27 -0500 Subject: [PATCH 13/13] Add extra Kompose documentation Create additional files for Kompose documentation including architecture, development, a more extensive index and a user guide. This also bumps Kompose up to the top on tools page to be symmetrical to the what's listed on the side navbar. I have assigned myself to each doc in order to get updates / any questions regarding the updating of documentation. --- _data/tools.yml | 5 +- docs/tools/kompose/index.md | 43 +++++ docs/tools/kompose/user-guide.md | 310 +++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+), 3 deletions(-) create mode 100644 docs/tools/kompose/index.md create mode 100644 docs/tools/kompose/user-guide.md diff --git a/_data/tools.yml b/_data/tools.yml index 31c355e9b0..8c09e7e095 100644 --- a/_data/tools.yml +++ b/_data/tools.yml @@ -14,8 +14,7 @@ toc: - title: Third-Party Tools section: + - docs/tools/kompose/index.md + - docs/tools/kompose/user-guide.md - title: Helm path: https://github.com/kubernetes/helm - - title: Kompose - path: https://github.com/kubernetes-incubator/kompose - diff --git a/docs/tools/kompose/index.md b/docs/tools/kompose/index.md new file mode 100644 index 0000000000..e39b6b0d3a --- /dev/null +++ b/docs/tools/kompose/index.md @@ -0,0 +1,43 @@ +--- + +assignees: +- cdrage + +title: Kompose Overview +--- + +`kompose` is a tool to help users who are familiar with `docker-compose` move to **Kubernetes**. `kompose` takes a Docker Compose file and translates it into Kubernetes resources. + +`kompose` is a convenience tool to go from local Docker development to managing your application with Kubernetes. Transformation of the Docker Compose format to Kubernetes resources manifest may not be exact, but it helps tremendously when first deploying an application on Kubernetes. + +## Use Case + +If you have a Docker Compose `docker-compose.yml` or a Docker Distributed Application Bundle `docker-compose-bundle.dab` file, you can convert it into Kubernetes deployments and services like this: + +```console +$ kompose --bundle docker-compose-bundle.dab convert +WARN[0000]: Unsupported key networks - ignoring +file "redis-svc.json" created +file "web-svc.json" created +file "web-deployment.json" created +file "redis-deployment.json" created + +$ kompose -f docker-compose.yml convert +WARN[0000]: Unsupported key networks - ignoring +file "redis-svc.json" created +file "web-svc.json" created +file "web-deployment.json" created +file "redis-deployment.json" created +``` + +## Installation + +Grab the latest [release](https://github.com/kubernetes-incubator/kompose/releases) for your OS, untar and extract the binary. + +### Linux + +```sh +wget https://github.com/kubernetes-incubator/kompose/releases/download/v0.1.2/kompose_linux-amd64.tar.gz +tar -xvf kompose_linux-amd64.tar.gz --strip 1 +sudo mv kompose /usr/local/bin +``` diff --git a/docs/tools/kompose/user-guide.md b/docs/tools/kompose/user-guide.md new file mode 100644 index 0000000000..8dbc221fe6 --- /dev/null +++ b/docs/tools/kompose/user-guide.md @@ -0,0 +1,310 @@ +--- + +assignees: +- cdrage + +title: Kompose User Guide +--- + +* TOC +{:toc} + +Kompose has support for two providers: OpenShift and Kubernetes. +You can choose targeted provider either using global option `--provider`, or by setting environment variable `PROVIDER`. +By setting environment variable `PROVIDER` you can permanently switch to OpenShift provider without need to always specify `--provider openshift` option. +If no provider is specified Kubernetes is default provider. + + +## Kompose convert + +Currently Kompose supports to transform either Docker Compose file (both of v1 and v2) and [experimental Distributed Application Bundles](https://blog.docker.com/2016/06/docker-app-bundle/) into Kubernetes and OpenShift objects. +There is a couple of sample files in the `examples/` directory for testing. +You will convert the compose or dab file to Kubernetes or OpenShift objects with `kompose convert`. + +### Kubernetes +```console +$ cd examples/ + +$ ls +docker-compose.yml docker-compose-bundle.dab docker-gitlab.yml docker-voting.yml + +$ kompose -f docker-gitlab.yml convert -y +file "redisio-svc.yaml" created +file "gitlab-svc.yaml" created +file "postgresql-svc.yaml" created +file "gitlab-deployment.yaml" created +file "postgresql-deployment.yaml" created +file "redisio-deployment.yaml" created + +$ ls *.yaml +gitlab-deployment.yaml postgresql-deployment.yaml redis-deployment.yaml redisio-svc.yaml web-deployment.yaml +gitlab-svc.yaml postgresql-svc.yaml redisio-deployment.yaml redis-svc.yaml web-svc.yaml +``` + +You can try with a Docker Compose version 2 like this: + +```console +$ kompose --file docker-voting.yml convert +WARN[0000]: Unsupported key networks - ignoring +WARN[0000]: Unsupported key build - ignoring +file "worker-svc.json" created +file "db-svc.json" created +file "redis-svc.json" created +file "result-svc.json" created +file "vote-svc.json" created +file "redis-deployment.json" created +file "result-deployment.json" created +file "vote-deployment.json" created +file "worker-deployment.json" created +file "db-deployment.json" created + +$ ls +db-deployment.json docker-compose.yml docker-gitlab.yml redis-deployment.json result-deployment.json vote-deployment.json worker-deployment.json +db-svc.json docker-compose-bundle.dab docker-voting.yml redis-svc.json result-svc.json vote-svc.json worker-svc.json +``` + +Using `--bundle, --dab` to specify a DAB file as below: + +```console +$ kompose --bundle docker-compose-bundle.dab convert +WARN[0000]: Unsupported key networks - ignoring +file "redis-svc.json" created +file "web-svc.json" created +file "web-deployment.json" created +file "redis-deployment.json" created +``` + +### OpenShift + +```console +$ kompose --provider openshift --file docker-voting.yml convert +WARN[0000] [worker] Service cannot be created because of missing port. +INFO[0000] file "vote-service.json" created +INFO[0000] file "db-service.json" created +INFO[0000] file "redis-service.json" created +INFO[0000] file "result-service.json" created +INFO[0000] file "vote-deploymentconfig.json" created +INFO[0000] file "vote-imagestream.json" created +INFO[0000] file "worker-deploymentconfig.json" created +INFO[0000] file "worker-imagestream.json" created +INFO[0000] file "db-deploymentconfig.json" created +INFO[0000] file "db-imagestream.json" created +INFO[0000] file "redis-deploymentconfig.json" created +INFO[0000] file "redis-imagestream.json" created +INFO[0000] file "result-deploymentconfig.json" created +INFO[0000] file "result-imagestream.json" created +``` + +In similar way you can convert DAB files to OpenShift. +```console$ +$ kompose --bundle docker-compose-bundle.dab --provider openshift convert +WARN[0000]: Unsupported key networks - ignoring +INFO[0000] file "redis-svc.json" created +INFO[0000] file "web-svc.json" created +INFO[0000] file "web-deploymentconfig.json" created +INFO[0000] file "web-imagestream.json" created +INFO[0000] file "redis-deploymentconfig.json" created +INFO[0000] file "redis-imagestream.json" created +``` + +## Kompose up + +Kompose supports a straightforward way to deploy your "composed" application to Kubernetes or OpenShift via `kompose up`. + + +### Kubernetes +```console +$ kompose --file ./examples/docker-guestbook.yml up +We are going to create Kubernetes deployments and services for your Dockerized application. +If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. + +INFO[0000] Successfully created service: redis-master +INFO[0000] Successfully created service: redis-slave +INFO[0000] Successfully created service: frontend +INFO[0001] Successfully created deployment: redis-master +INFO[0001] Successfully created deployment: redis-slave +INFO[0001] Successfully created deployment: frontend + +Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details. + +$ kubectl get deployment,svc,pods +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +frontend 1 1 1 1 4m +redis-master 1 1 1 1 4m +redis-slave 1 1 1 1 4m +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +frontend 10.0.174.12 80/TCP 4m +kubernetes 10.0.0.1 443/TCP 13d +redis-master 10.0.202.43 6379/TCP 4m +redis-slave 10.0.1.85 6379/TCP 4m +NAME READY STATUS RESTARTS AGE +frontend-2768218532-cs5t5 1/1 Running 0 4m +redis-master-1432129712-63jn8 1/1 Running 0 4m +redis-slave-2504961300-nve7b 1/1 Running 0 4m +``` +Note: + +- You must have a running Kubernetes cluster with a pre-configured kubectl context. +- Only deployments and services are generated and deployed to Kubernetes. If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. + +### OpenShift +```console +$kompose --file ./examples/docker-guestbook.yml --provider openshift up +We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application. +If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. + +INFO[0000] Successfully created service: redis-slave +INFO[0000] Successfully created service: frontend +INFO[0000] Successfully created service: redis-master +INFO[0000] Successfully created deployment: redis-slave +INFO[0000] Successfully created ImageStream: redis-slave +INFO[0000] Successfully created deployment: frontend +INFO[0000] Successfully created ImageStream: frontend +INFO[0000] Successfully created deployment: redis-master +INFO[0000] Successfully created ImageStream: redis-master + +Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details. + +$ oc get dc,svc,is +NAME REVISION DESIRED CURRENT TRIGGERED BY +dc/frontend 0 1 0 config,image(frontend:v4) +dc/redis-master 0 1 0 config,image(redis-master:e2e) +dc/redis-slave 0 1 0 config,image(redis-slave:v1) +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +svc/frontend 172.30.46.64 80/TCP 8s +svc/redis-master 172.30.144.56 6379/TCP 8s +svc/redis-slave 172.30.75.245 6379/TCP 8s +NAME DOCKER REPO TAGS UPDATED +is/frontend 172.30.12.200:5000/fff/frontend +is/redis-master 172.30.12.200:5000/fff/redis-master +is/redis-slave 172.30.12.200:5000/fff/redis-slave v1 +``` + +Note: + +- You must have a running OpenShift cluster with a pre-configured `oc` context (`oc login`) + +## Kompose down + +Once you have deployed "composed" application to Kubernetes, `kompose down` will help you to take the application out by deleting its deployments and services. If you need to remove other resources, use the 'kubectl' command. + +```console +$ kompose --file docker-guestbook.yml down +INFO[0000] Successfully deleted service: redis-master +INFO[0004] Successfully deleted deployment: redis-master +INFO[0004] Successfully deleted service: redis-slave +INFO[0008] Successfully deleted deployment: redis-slave +INFO[0009] Successfully deleted service: frontend +INFO[0013] Successfully deleted deployment: frontend +``` +Note: +- You must have a running Kubernetes cluster with a pre-configured kubectl context. + +## Alternate formats + +The default `kompose` transformation will generate Kubernetes [Deployments](http://kubernetes.io/docs/user-guide/deployments/) and [Services](http://kubernetes.io/docs/user-guide/services/), in json format. You have alternative option to generate yaml with `-y`. Also, you can alternatively generate [Replication Controllers](http://kubernetes.io/docs/user-guide/replication-controller/) objects, [Deamon Sets](http://kubernetes.io/docs/admin/daemons/), or [Helm](https://github.com/helm/helm) charts. + +```console +$ kompose convert +file "redis-svc.json" created +file "web-svc.json" created +file "redis-deployment.json" created +file "web-deployment.json" created +``` +The `*-deployment.json` files contain the Deployment objects. + +```console +$ kompose convert --rc -y +file "redis-svc.yaml" created +file "web-svc.yaml" created +file "redis-rc.yaml" created +file "web-rc.yaml" created +``` + +The `*-rc.yaml` files contain the Replication Controller objects. If you want to specify replicas (default is 1), use `--replicas` flag: `$ kompose convert --rc --replicas 3 -y` + +```console +$ kompose convert --ds -y +file "redis-svc.yaml" created +file "web-svc.yaml" created +file "redis-daemonset.yaml" created +file "web-daemonset.yaml" created +``` + +The `*-daemonset.yaml` files contain the Daemon Set objects + +If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) simply do: + +```console +$ kompose convert -c -y +file "web-svc.yaml" created +file "redis-svc.yaml" created +file "web-deployment.yaml" created +file "redis-deployment.yaml" created +chart created in "./docker-compose/" + +$ tree docker-compose/ +docker-compose +├── Chart.yaml +├── README.md +└── templates + ├── redis-deployment.yaml + ├── redis-svc.yaml + ├── web-deployment.yaml + └── web-svc.yaml +``` + +The chart structure is aimed at providing a skeleton for building your Helm charts. + +## Unsupported docker-compose configuration options + +Currently `kompose` does not support the following Docker Compose options. + +``` +"build", "cgroup_parent", "devices", "depends_on", "dns", "dns_search", "domainname", "env_file", "extends", "external_links", "extra_hosts", "hostname", "ipc", "logging", "mac_address", "mem_limit", "memswap_limit", "network_mode", "networks", "pid", "security_opt", "shm_size", "stop_signal", "volume_driver", "uts", "read_only", "stdin_open", "tty", "user", "ulimits", "dockerfile", "net" +``` + +For example: + +```console +$ cat nginx.yml +nginx: + image: nginx + dockerfile: foobar + build: ./foobar + cap_add: + - ALL + container_name: foobar + +$ kompose -f nginx.yml convert +WARN[0000] Unsupported key build - ignoring +WARN[0000] Unsupported key cap_add - ignoring +WARN[0000] Unsupported key dockerfile - ignoring +``` + +## Labels + +`kompose` supports Kompose-specific labels within the `docker-compose.yml` file in order to explicitly imply a service type upon conversion. + +The currently supported options are: + +| Key | Value | +|----------------------|-------------------------------------| +| kompose.service.type | nodeport / clusterip / loadbalancer | + + +Here is a brief example that uses the annotations / labels feature to specify a service type: + +```yaml +version: "2" +services: + nginx: + image: nginx + dockerfile: foobar + build: ./foobar + cap_add: + - ALL + container_name: foobar + labels: + kompose.service.type: nodeport +```