deep-stack/kompose
4
0
Fork 0
forked from LaconicNetwork/kompose
Code Pull Requests Activity

Fixes typos (#1557)

Browse Source 
* rebase

* undo commit to assets/**/*

* undo commit in script/test/*

* Apply suggestions from code review

Co-authored-by: AhmedGrati <48932084+AhmedGrati@users.noreply.github.com>

* removes webrick

---------

Co-authored-by: AhmedGrati <48932084+AhmedGrati@users.noreply.github.com>
This commit is contained in:
Patrick Rachford
2023-02-08 14:51:09 -05:00
committed by GitHub
co-authored by AhmedGrati
parent b3d4aec3ee
commit 35a430614f
18 changed files with 388 additions and 356 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide.md
+89 -91
View File
@@ -2,20 +2,19 @@
layout: default
permalink: /user-guide/
title: User Guide
redirect_from:
redirect_from:
- /docs/user-guide.md/
- /docs/user-guide/
---
# User Guide
* TOC
{:toc}
- TOC
{:toc}
Kompose has support for two providers: OpenShift and Kubernetes.
You can choose a targeted provider using global option `--provider`. If no provider is specified, Kubernetes is set by default.
## Kompose Convert
Kompose supports conversion of V1, V2, and V3 Docker Compose files into Kubernetes and OpenShift objects.
@@ -46,60 +45,60 @@ You can also provide multiple docker-compose files at the same time:
```sh
$ kompose -f docker-compose.yml -f docker-guestbook.yml convert
INFO Kubernetes file "frontend-service.yaml" created
INFO Kubernetes file "mlbparks-service.yaml" created
INFO Kubernetes file "mongodb-service.yaml" created
INFO Kubernetes file "redis-master-service.yaml" created
INFO Kubernetes file "redis-slave-service.yaml" created
INFO Kubernetes file "frontend-deployment.yaml" created
INFO Kubernetes file "mlbparks-deployment.yaml" created
INFO Kubernetes file "mongodb-deployment.yaml" created
INFO Kubernetes file "mongodb-claim0-persistentvolumeclaim.yaml" created
INFO Kubernetes file "redis-master-deployment.yaml" created
INFO Kubernetes file "redis-slave-deployment.yaml" created
INFO Kubernetes file "frontend-service.yaml" created
INFO Kubernetes file "mlbparks-service.yaml" created
INFO Kubernetes file "mongodb-service.yaml" created
INFO Kubernetes file "redis-master-service.yaml" created
INFO Kubernetes file "redis-slave-service.yaml" created
INFO Kubernetes file "frontend-deployment.yaml" created
INFO Kubernetes file "mlbparks-deployment.yaml" created
INFO Kubernetes file "mongodb-deployment.yaml" created
INFO Kubernetes file "mongodb-claim0-persistentvolumeclaim.yaml" created
INFO Kubernetes file "redis-master-deployment.yaml" created
INFO Kubernetes file "redis-slave-deployment.yaml" created
$ ls
mlbparks-deployment.yaml mongodb-service.yaml redis-slave-service.jsonmlbparks-service.yaml
mlbparks-deployment.yaml mongodb-service.yaml redis-slave-service.jsonmlbparks-service.yaml
frontend-deployment.yaml mongodb-claim0-persistentvolumeclaim.yaml redis-master-service.yaml
frontend-service.yaml mongodb-deployment.yaml redis-slave-deployment.yaml
redis-master-deployment.yaml
```
```
When multiple docker-compose files are provided the configuration is merged. Any configuration that is common will be over ridden by subsequent file.
### OpenShift
```sh
$ kompose --provider openshift --file docker-voting.yml convert
WARN [worker] Service cannot be created because of missing port.
INFO OpenShift file "vote-service.yaml" created
INFO OpenShift file "db-service.yaml" created
INFO OpenShift file "redis-service.yaml" created
INFO OpenShift file "result-service.yaml" created
INFO OpenShift file "vote-deploymentconfig.yaml" created
INFO OpenShift file "vote-imagestream.yaml" created
INFO OpenShift file "worker-deploymentconfig.yaml" created
INFO OpenShift file "worker-imagestream.yaml" created
INFO OpenShift file "db-deploymentconfig.yaml" created
INFO OpenShift file "db-imagestream.yaml" created
INFO OpenShift file "redis-deploymentconfig.yaml" created
INFO OpenShift file "redis-imagestream.yaml" created
INFO OpenShift file "result-deploymentconfig.yaml" created
INFO OpenShift file "result-imagestream.yaml" created
INFO OpenShift file "vote-service.yaml" created
INFO OpenShift file "db-service.yaml" created
INFO OpenShift file "redis-service.yaml" created
INFO OpenShift file "result-service.yaml" created
INFO OpenShift file "vote-deploymentconfig.yaml" created
INFO OpenShift file "vote-imagestream.yaml" created
INFO OpenShift file "worker-deploymentconfig.yaml" created
INFO OpenShift file "worker-imagestream.yaml" created
INFO OpenShift file "db-deploymentconfig.yaml" created
INFO OpenShift file "db-imagestream.yaml" created
INFO OpenShift file "redis-deploymentconfig.yaml" created
INFO OpenShift file "redis-imagestream.yaml" created
INFO OpenShift file "result-deploymentconfig.yaml" created
INFO OpenShift file "result-imagestream.yaml" created
```
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.
It also supports creating buildconfig for build directive in a service. By default, it uses the remote repository for the current git branch as the source repository, and the current branch as the source branch for the build. You can specify a different source repository and branch using `--build-repo` and `--build-branch` options respectively.
```sh
$ kompose --provider openshift --file buildconfig/docker-compose.yml convert
WARN [foo] Service cannot be created because of missing port.
INFO OpenShift Buildconfig using git@github.com:rtnpro/kompose.git::master as source.
INFO OpenShift file "foo-deploymentconfig.yaml" created
INFO OpenShift file "foo-imagestream.yaml" created
INFO OpenShift file "foo-buildconfig.yaml" created
WARN [foo] Service cannot be created because of missing port.
INFO OpenShift Buildconfig using git@github.com:rtnpro/kompose.git::master as source.
INFO OpenShift file "foo-deploymentconfig.yaml" created
INFO OpenShift file "foo-imagestream.yaml" created
INFO OpenShift file "foo-buildconfig.yaml" created
```
**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 .
**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 work around this Openshift issue: https://github.com/openshift/origin/issues/4518 .
## Alternative Conversions
@@ -112,6 +111,7 @@ INFO Kubernetes file "web-svc.json" created
INFO Kubernetes file "redis-deployment.json" created
INFO Kubernetes file "web-deployment.json" created
```
The `*-deployment.json` files contain the Deployment objects.
```sh
@@ -136,19 +136,18 @@ The `*-daemonset.yaml` files contain the Daemon Set objects
```sh
$ kompose convert --controller statefulset
INFO Kubernetes file "db-service.yaml" created
INFO Kubernetes file "wordpress-service.yaml" created
INFO Kubernetes file "db-statefulset.yaml" created
INFO Kubernetes file "wordpress-statefulset.yaml" created
INFO Kubernetes file "db-service.yaml" created
INFO Kubernetes file "wordpress-service.yaml" created
INFO Kubernetes file "db-statefulset.yaml" created
INFO Kubernetes file "wordpress-statefulset.yaml" created
```
The `*statefulset-.yaml` files contain the Statefulset objects.
If you want to generate a Chart to be used with [Helm](https://github.com/kubernetes/helm) simply do:
```sh
$ kompose convert -c
$ kompose convert -c
INFO Kubernetes file "web-svc.yaml" created
INFO Kubernetes file "redis-svc.yaml" created
INFO Kubernetes file "web-deployment.yaml" created
@@ -175,44 +174,42 @@ explicitly define the generated resources' behavior upon conversion, like Servic
The currently supported options are:
| Key | Value |
|----------------------|-------------------------------------|
| kompose.service.type | nodeport / clusterip / loadbalancer / headless |
| kompose.service.group | name to group the containers contained in a single pod |
| kompose.service.expose | true / hostnames (separated by comma) |
| kompose.service.nodeport.port | port value (string) |
| kompose.service.expose.tls-secret | secret name |
| kompose.service.expose.ingress-class-name | ingress class name |
| kompose.volume.size | kubernetes supported volume size |
| kompose.volume.storage-class-name | kubernetes supported volume storageClassName |
| kompose.volume.type | use k8s volume type, eg "configMap", "persistentVolumeClaim", "emptyDir", "hostPath" |
| kompose.controller.type | deployment / daemonset / replicationcontroller |
| kompose.image-pull-policy | kubernetes pods imagePullPolicy |
| kompose.image-pull-secret | kubernetes secret name for imagePullSecrets |
| kompose.service.healthcheck.readiness.disable | kubernetes readiness disable |
| kompose.service.healthcheck.readiness.test | kubernetes readiness exec command |
| kompose.service.healthcheck.readiness.http_get_path | kubernetes readiness httpGet path |
| kompose.service.healthcheck.readiness.http_get_port | kubernetes readiness httpGet port |
| kompose.service.healthcheck.readiness.tcp_port | kubernetes readiness tcpSocket port |
| kompose.service.healthcheck.readiness.interval | kubernetes readiness interval value |
| kompose.service.healthcheck.readiness.timeout | kubernetes readiness timeout value |
| kompose.service.healthcheck.readiness.retries | kubernetes readiness retries value |
| kompose.service.healthcheck.readiness.start_period | kubernetes readiness start_period |
| kompose.service.healthcheck.liveness.http_get_path | kubernetes liveness httpGet path |
| kompose.service.healthcheck.liveness.http_get_port | kubernetes liveness httpGet port |
| kompose.service.healthcheck.liveness.tcp_port | kubernetes liveness tcpSocket port |
| Key | Value |
| --------------------------------------------------- | ------------------------------------------------------------------------------------ |
| kompose.service.type | nodeport / clusterip / loadbalancer / headless |
| kompose.service.group | name to group the containers contained in a single pod |
| kompose.service.expose | true / hostnames (separated by comma) |
| kompose.service.nodeport.port | port value (string) |
| kompose.service.expose.tls-secret | secret name |
| kompose.service.expose.ingress-class-name | ingress class name |
| kompose.volume.size | kubernetes supported volume size |
| kompose.volume.storage-class-name | kubernetes supported volume storageClassName |
| kompose.volume.type | use k8s volume type, eg "configMap", "persistentVolumeClaim", "emptyDir", "hostPath" |
| kompose.controller.type | deployment / daemonset / replicationcontroller |
| kompose.image-pull-policy | kubernetes pods imagePullPolicy |
| kompose.image-pull-secret | kubernetes secret name for imagePullSecrets |
| kompose.service.healthcheck.readiness.disable | kubernetes readiness disable |
| kompose.service.healthcheck.readiness.test | kubernetes readiness exec command |
| kompose.service.healthcheck.readiness.http_get_path | kubernetes readiness httpGet path |
| kompose.service.healthcheck.readiness.http_get_port | kubernetes readiness httpGet port |
| kompose.service.healthcheck.readiness.tcp_port | kubernetes readiness tcpSocket port |
| kompose.service.healthcheck.readiness.interval | kubernetes readiness interval value |
| kompose.service.healthcheck.readiness.timeout | kubernetes readiness timeout value |
| kompose.service.healthcheck.readiness.retries | kubernetes readiness retries value |
| kompose.service.healthcheck.readiness.start_period | kubernetes readiness start_period |
| kompose.service.healthcheck.liveness.http_get_path | kubernetes liveness httpGet path |
| kompose.service.healthcheck.liveness.http_get_port | kubernetes liveness httpGet port |
| kompose.service.healthcheck.liveness.tcp_port | kubernetes liveness tcpSocket port |
**Note**: `kompose.service.type` label should be defined with `ports` only (except for headless service), otherwise `kompose` will fail.
- `kompose.service.type` defines the type of service to be created.
For example:
```yaml
version: "2"
services:
services:
nginx:
image: nginx
dockerfile: foobar
@@ -220,11 +217,11 @@ services:
cap_add:
- ALL
container_name: foobar
labels:
labels:
kompose.service.type: nodeport
```
- `kompose.service.group` defines the group of containers included in a single pod.
- `kompose.service.group` defines the group of containers included in a single pod.
For example:
@@ -236,19 +233,19 @@ services:
image: nginx
depends_on:
- logs
labels:
labels:
- kompose.service.group=sidecar
logs:
image: busybox
command: ["tail -f /var/log/nginx/access.log"]
labels:
labels:
- kompose.service.group=sidecar
```
- `kompose.service.expose` defines if the service needs to be made accessible from outside the cluster or not. If the value is set to "true", the provider sets the endpoint automatically, and for any other value, the value is set as the hostname. If multiple ports are defined in a service, the first one is chosen to be the exposed.
- For the Kubernetes provider, an ingress resource is created and it is assumed that an ingress controller has already been configured. If the value is set to a comma sepatated list, multiple hostnames are supported.Hostname with path is also supported.
- For the OpenShift provider, a route is created.
- For the Kubernetes provider, an ingress resource is created, and it is assumed that an ingress controller has already been configured. If the value is set to a comma-separated list, multiple hostnames are supported. Hostname with the path is also supported.
- For the OpenShift provider, a route is created.
- `kompose.service.nodeport.port` defines the port value when service type is `nodeport`, this label should only be set when the service only contains 1 port. Usually kubernetes define a port range for node port values, kompose will not validate this.
- `kompose.service.expose.tls-secret` provides the name of the TLS secret to use with the Kubernetes ingress controller. This requires kompose.service.expose to be set.
- `kompose.service.expose.ingress-class-name` provides the name of ingress class to use with the Kubernetes ingress controller. This requires kompose.service.
@@ -288,8 +285,8 @@ services:
```
- `kompose.image-pull-secret` defines a kubernetes secret name for imagePullSecrets podspec field.
This secret will be used for pulling private images.
For example:
This secret will be used for pulling private images.
For example:
```yaml
version: '2'
@@ -300,8 +297,8 @@ services:
kompose.image-pull-secret: "example-kubernetes-secret"
```
- `kompose.volume.size` defines the requests storage's size in the PersistentVolumeClaim, or you can use command line parameter `--pvc-request-size`.
The priority follow label (kompose.volume.size) > command parameter(--pvc-request-size) > defaultSize (100Mi)
- `kompose.volume.size` defines the requests storage's size in the PersistentVolumeClaim, or you can use the command line parameter `--pvc-request-size`.
- The priority follows label (kompose.volume.size) > command parameter(--pvc-request-size) > defaultSize (100Mi)
For example:
@@ -378,7 +375,6 @@ services:
kompose.image-pull-policy: "Never"
```
For example:
```yaml
@@ -412,6 +408,7 @@ services:
kompose.service.healthcheck.readiness.retries: 3
kompose.service.healthcheck.readiness.start_period: 30s
```
- `kompose.service.healthcheck.readiness` defines Kubernetes [readiness](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes)
## Restart
@@ -419,7 +416,7 @@ services:
If you want to create normal pods without controller you can use `restart` construct of docker-compose to define that. Follow table below to see what happens on the `restart` value.
| `docker-compose` `restart` | object created | Pod `restartPolicy` |
|----------------------------|-------------------|---------------------|
| -------------------------- | ----------------- | ------------------- |
| `""` | controller object | `Always` |
| `always` | controller object | `Always` |
| `unless-stopped` | controller object | `Always` |
@@ -452,9 +449,9 @@ Please note that changing service name might break some `docker-compose` files.
If the Docker Compose file has `build` or `build:context, build:dockerfile` keys, build will run when `--build` specified.
And Image will push to *docker.io* (default) when `--push-image=true` specified.
And Image will push to _docker.io_ (default) when `--push-image=true` specified.
It is possible to push to custom registry by specify `--push-image-registry`, which will override the registry from image name.
It is possible to push to custom registry by specify `--push-image-registry`, which will override the registry from image name.
### Authentication on registry
@@ -463,12 +460,13 @@ Kompose uses the docker authentication from file `$DOCKER_CONFIG/config.json`, `
**This only works fine on Linux but macOS would fail when using `"credsStore": "osxkeychain"`.**
However, there is an approach to push successfully on macOS, by not using `osxkeychain` for `credsStore`. To disable `osxkeychain`:
* remove `credsStore` from `config.json` file, and `docker login` again.
* for some docker desktop versions, there is a setting `Securely store Docker logins in macOS keychain`, which should be unchecked. Then restart docker desktop if needed, and `docker login` again.
- remove `credsStore` from `config.json` file, and `docker login` again.
- for some docker desktop versions, there is a setting `Securely store Docker logins in macOS keychain`, which should be unchecked. Then restart docker desktop if needed, and `docker login` again.
Now `config.json` should contain base64 encoded passwords, then push image should succeed. Working, but not safe though! Use it at your risk.
For Windows, there is also `credsStore` which is `wincred`. Technically it will fail on authentication as macOS does, but you can try the approach above like macOS too.
For Windows, there is also `credsStore` which is `wincred`. Technically it will fail on authentication as macOS does, but you can try the approach above like macOS too.
## Docker Compose Versions