You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Update documentation to reflect build/push and v3 changes
Adds a user guide on how to use the build/push functionality of Docker
images to the user guide.
Adds v3 documentation as well as cleans up the user guide as well.
I also do minor changes such as removing `$ ` in the CLI examples, as
it's easier to copy and paste without the `$ ` there (when double
clicking).
I've also changed the `console` yaml indicitors to `sh` since it doesn't
matter / it's aliased, see:
https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
Kompose has support for two providers: OpenShift and Kubernetes.
12
15
You can choose targeted provider either using global option `--provider`, or by setting environment variable `PROVIDER`.
13
16
By setting environment variable `PROVIDER` you can permanently switch to OpenShift provider without need to always specify `--provider openshift` option.
14
17
If no provider is specified Kubernetes is default provider.
15
18
16
19
17
-
## Kompose convert
20
+
## `kompose convert`
18
21
19
22
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.
20
23
There is a couple of sample files in the `examples/` directory for testing.
21
-
You will convert the compose or dab file to Kubernetes or OpenShift objects with `kompose convert`.
24
+
You will convert the compose or dab file to Kubernetes or OpenShift objects with `$ kompose convert`.
22
25
23
26
### Kubernetes
24
-
```console
27
+
```sh
25
28
$ cd examples/
26
29
27
30
$ ls
@@ -42,7 +45,7 @@ gitlab-svc.yaml postgresql-svc.yaml redisio-deployment.yaml red
42
45
43
46
You can try with a Docker Compose version 2 like this:
@@ -133,7 +136,7 @@ INFO OpenShift file "redis-imagestream.yaml" created
133
136
134
137
It also supports creating buildconfig for build directive in a service. By default, it uses the remote repo for the current git branch as the source repo, and the current branch as the source branch for the build. You can specify a different source repo and branch using ``--build-repo`` and ``--build-branch`` options respectively.
WARN [foo] Service cannot be created because of missing port.
139
142
INFO OpenShift Buildconfig using git@github.com:rtnpro/kompose.git::master as source.
@@ -144,13 +147,13 @@ INFO OpenShift file "foo-buildconfig.yaml" created
144
147
145
148
**Note**: If you are manually pushing the Openshift artifacts using ``oc create -f``, you need to ensure that you push the imagestream artifact before the buildconfig artifact, to workaround this Openshift issue: https://github.com/openshift/origin/issues/4518 .
146
149
147
-
## Kompose up
150
+
## `kompose up`
148
151
149
152
Kompose supports a straightforward way to deploy your "composed" application to Kubernetes or OpenShift via `kompose up`.
150
153
151
154
152
155
### Kubernetes
153
-
```console
156
+
```sh
154
157
$ kompose --file ./examples/docker-guestbook.yml up
155
158
We are going to create Kubernetes deployments and services for your Dockerized application.
156
159
If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead.
@@ -186,8 +189,8 @@ Note:
186
189
- 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.
187
190
188
191
### OpenShift
189
-
```console
190
-
$kompose --file ./examples/docker-guestbook.yml --provider openshift up
192
+
```sh
193
+
$kompose --file ./examples/docker-guestbook.yml --provider openshift up
191
194
We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application.
192
195
If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead.
- You must have a running OpenShift cluster with a pre-configured `oc` context (`oc login`)
223
226
224
-
## Kompose down
227
+
## `kompose down`
225
228
226
-
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.
229
+
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.
227
230
228
-
```console
231
+
```sh
229
232
$ kompose --file docker-guestbook.yml down
230
233
INFO Successfully deleted service: redis-master
231
234
INFO Successfully deleted deployment: redis-master
@@ -237,11 +240,55 @@ INFO Successfully deleted deployment: frontend
237
240
Note:
238
241
- You must have a running Kubernetes cluster with a pre-configured kubectl context.
239
242
240
-
## Alternate formats
243
+
## Building and Pushing Docker Images
244
+
245
+
Kompose supports both building and pushing Docker images. When using the `build` key within your Docker Compose file, your image will automatically be built and pushed.
246
+
247
+
Using an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes-incubator/kompose/master/examples/buildconfig/docker-compose.yml):
248
+
249
+
```yaml
250
+
version: "2"
251
+
252
+
services:
253
+
foo:
254
+
build: "./build"
255
+
image: docker.io/foo/bar
256
+
```
257
+
258
+
Using `kompose up` with a `build` key:
259
+
260
+
```sh
261
+
$ kompose up
262
+
INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar'
263
+
INFO Building image 'docker.io/foo/bar' from directory 'build'
264
+
INFO Image 'docker.io/foo/bar' from directory 'build' built successfully
265
+
INFO Pushing image 'foo/bar:latest' to registry 'docker.io'
266
+
INFO Attempting authentication credentials 'https://index.docker.io/v1/
267
+
INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io'
268
+
INFO We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead.
269
+
270
+
INFO Deploying application in "default" namespace
271
+
INFO Successfully created Service: foo
272
+
INFO Successfully created Deployment: foo
273
+
274
+
Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details.
275
+
```
276
+
277
+
In order to disable the functionality, or choose to use BuildConfig generation (with OpenShift) `--build (local|build-config|none)` can be passed.
278
+
279
+
```sh
280
+
# Disable building/pushing Docker images
281
+
$ kompose up --build none
282
+
283
+
# Generate Build Config artifacts for OpenShift
284
+
$ kompose up --provider openshift --build build-config
285
+
```
286
+
287
+
## Alternative Conversions
241
288
242
289
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 yaml format. You have alternative option to generate json with `-j`. 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.
243
290
244
-
```console
291
+
```sh
245
292
$ kompose convert -j
246
293
INFO Kubernetes file "redis-svc.json" created
247
294
INFO Kubernetes file "web-svc.json" created
@@ -250,7 +297,7 @@ INFO Kubernetes file "web-deployment.json" created
250
297
```
251
298
The `*-deployment.json` files contain the Deployment objects.
252
299
253
-
```console
300
+
```sh
254
301
$ kompose convert --replication-controller
255
302
INFO Kubernetes file "redis-svc.yaml" created
256
303
INFO Kubernetes file "web-svc.yaml" created
@@ -260,7 +307,7 @@ INFO Kubernetes file "web-replicationcontroller.yaml" created
260
307
261
308
The `*-replicationcontroller.yaml` files contain the Replication Controller objects. If you want to specify replicas (default is 1), use `--replicas` flag: `$ kompose convert --replication-controller --replicas 3`
262
309
263
-
```console
310
+
```sh
264
311
$ kompose convert --daemon-set
265
312
INFO Kubernetes file "redis-svc.yaml" created
266
313
INFO Kubernetes file "web-svc.yaml" created
@@ -272,15 +319,15 @@ The `*-daemonset.yaml` files contain the Daemon Set objects
272
319
273
320
If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) simply do:
274
321
275
-
```console
322
+
```sh
276
323
$ kompose convert -c
277
324
INFO Kubernetes file "web-svc.yaml" created
278
325
INFO Kubernetes file "redis-svc.yaml" created
279
326
INFO Kubernetes file "web-deployment.yaml" created
280
327
INFO Kubernetes file "redis-deployment.yaml" created
281
328
chart created in "./docker-compose/"
282
329
283
-
$ tree docker-compose/
330
+
tree docker-compose/
284
331
docker-compose
285
332
├── Chart.yaml
286
333
├── README.md
@@ -293,28 +340,6 @@ docker-compose
293
340
294
341
The chart structure is aimed at providing a skeleton for building your Helm charts.
Currently `kompose` does not support some Docker Compose options, which are listed on the [conversion](/docs/conversion.md) document.
299
-
300
-
For example:
301
-
302
-
```console
303
-
$ cat nginx.yml
304
-
nginx:
305
-
image: nginx
306
-
dockerfile: foobar
307
-
build: ./foobar
308
-
cap_add:
309
-
- ALL
310
-
container_name: foobar
311
-
312
-
$ kompose -f nginx.yml convert
313
-
WARN Unsupported key build - ignoring
314
-
WARN Unsupported key cap_add - ignoring
315
-
WARN Unsupported key dockerfile - ignoring
316
-
```
317
-
318
343
## Labels
319
344
320
345
`kompose`supports Kompose-specific labels within the `docker-compose.yml` file in order to explicitly define a service's behavior upon conversion.
@@ -394,11 +419,16 @@ services:
394
419
restart: "on-failure"
395
420
```
396
421
397
-
398
422
#### Warning about Deployment Config's
399
423
400
424
If the Docker Compose file has a volume specified for a service, the Deployment (Kubernetes) or DeploymentConfig (OpenShift) strategy is changed to "Recreate" instead of "RollingUpdate" (default). This is done to avoid multiple instances of a service from accessing a volume at the same time.
401
425
402
426
If the Docker Compose file has service name with `_` in it (eg.`web_service`), then it will be replaced by `-` and the service name will be renamed accordingly (eg.`web-service`). Kompose does this because "Kubernetes" doesn't allow `_` in object name.
403
427
404
-
Please note that changing service name might break some `docker-compose` files.
428
+
Please note that changing service name might break some `docker-compose` files.
429
+
430
+
## Docker Compose Versions
431
+
432
+
Kompose supports Docker Compose versions: 1, 2 and 3. We have limited support on versions 2.1 and 3.2 due to their experimental nature.
433
+
434
+
A full list on compatibility between all three versions is listed in our [conversion document](/docs/conversion.md) including a list of all incompatible Docker Compose keys.
0 commit comments