From 6a5c64600ed7cb1a04430425ab40c4405727eb2e Mon Sep 17 00:00:00 2001 From: Charlie Drage Date: Sun, 2 Jun 2024 14:47:10 -0400 Subject: [PATCH] docs: update user guide (#1882) * docs: update user guide #### What type of PR is this? /kind documentation #### What this PR does / why we need it: Updates the user guide completely revamp it / describe each label. #### Which issue(s) this PR fixes: Closes https://github.com/kubernetes/kompose/issues/1584 Closes https://github.com/kubernetes/kompose/issues/1577 #### Special notes for your reviewer: Signed-off-by: Charlie Drage Please check the docs examples / each label that it's okay! * Update docs/user-guide.md Co-authored-by: TessaIO * Update docs/user-guide.md Co-authored-by: TessaIO * Update docs/user-guide.md Co-authored-by: TessaIO * update capitalization Signed-off-by: Charlie Drage --------- Signed-off-by: Charlie Drage Co-authored-by: TessaIO --- docs/user-guide.md | 765 ++++++++++++++++++++++----------------------- 1 file changed, 379 insertions(+), 386 deletions(-) diff --git a/docs/user-guide.md b/docs/user-guide.md index 727fb1195..da5007933 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -9,59 +9,29 @@ redirect_from: # User Guide -* TOC -{:toc} +## Table of contents -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 conversion example](#kompose-conversion-example) +* [CLI Modifications](#cli-modifications) +* [Labels](#labels) +* [Restart Policy](#restart-policy) +* [Building and Pushing Images](#building-and-pushing-images) -## Kompose Convert +## Kompose Conversion Example -Kompose supports conversion of V1, V2, and V3 Compose files into Kubernetes and OpenShift objects. +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. ### Kubernetes ```sh -$ kompose --file docker-voting.yml convert -WARN Unsupported key networks - ignoring -WARN Unsupported key build - ignoring -INFO Kubernetes file "worker-svc.yaml" created -INFO Kubernetes file "db-svc.yaml" created -INFO Kubernetes file "redis-svc.yaml" created -INFO Kubernetes file "result-svc.yaml" created -INFO Kubernetes file "vote-svc.yaml" created -INFO Kubernetes file "redis-deployment.yaml" created -INFO Kubernetes file "result-deployment.yaml" created -INFO Kubernetes file "vote-deployment.yaml" created -INFO Kubernetes file "worker-deployment.yaml" created -INFO Kubernetes file "db-deployment.yaml" created - -$ ls -db-deployment.yaml compose.yml docker-gitlab.yml redis-deployment.yaml result-deployment.yaml vote-deployment.yaml worker-deployment.yaml -db-svc.yaml docker-voting.yml redis-svc.yaml result-svc.yaml vote-svc.yaml worker-svc.yaml +$ kompose --file compose.yaml convert ``` You can also provide multiple compose files at the same time: ```sh -$ kompose -f 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-leader-service.yaml" created -INFO Kubernetes file "redis-replica-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-leader-deployment.yaml" created -INFO Kubernetes file "redis-replica-deployment.yaml" created - -$ ls -mlbparks-deployment.yaml mongodb-service.yaml redis-replica-service.jsonmlbparks-service.yaml -frontend-deployment.yaml mongodb-claim0-persistentvolumeclaim.yaml redis-leader-service.yaml -frontend-service.yaml mongodb-deployment.yaml redis-replica-deployment.yaml -redis-leader-deployment.yaml +$ kompose -f compose.yaml -f compose.yaml convert ``` When multiple compose files are provided the configuration is merged. Any configuration that is common will be over ridden by subsequent file. @@ -74,501 +44,528 @@ $ COMPOSE_FILE="compose.yaml alternative-compose.yaml" kompose convert ### 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 -``` - -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/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 +$ kompose --provider openshift --file compose.yaml convert ``` -**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 - -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, [Daemon Sets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) or [Helm](https://github.com/helm/helm) charts. +## CLI Modifications -```sh -$ kompose convert -j -INFO Kubernetes file "redis-svc.json" created -INFO Kubernetes file "web-svc.json" created -INFO Kubernetes file "redis-deployment.json" created -INFO Kubernetes file "web-deployment.json" created -``` +On the command line, you can modify the output of the generated YAML. For example, using alternative controllers such as [Replication Controllers](http://kubernetes.io/docs/user-guide/replication-controller/) objects, [Daemon Sets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), or [Statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/). -The `*-deployment.json` files contain the Deployment objects. - -```sh -$ kompose convert --controller replicationController -INFO Kubernetes file "redis-svc.yaml" created -INFO Kubernetes file "web-svc.yaml" created -INFO Kubernetes file "redis-replicationcontroller.yaml" created -INFO Kubernetes file "web-replicationcontroller.yaml" created -``` -The `*-replicationcontroller.yaml` files contain the Replication Controller objects. If you want to specify replicas (default is 1), use `--replicas` flag: `$ kompose convert --controller replicationController --replicas 3` +Daemon Set example: ```sh $ kompose convert --controller daemonSet -INFO Kubernetes file "redis-svc.yaml" created -INFO Kubernetes file "web-svc.yaml" created -INFO Kubernetes file "redis-daemonset.yaml" created -INFO Kubernetes file "web-daemonset.yaml" created -``` - -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 ``` -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 -INFO Kubernetes file "web-svc.yaml" created -INFO Kubernetes file "redis-svc.yaml" created -INFO Kubernetes file "web-deployment.yaml" created -INFO Kubernetes file "redis-deployment.yaml" created -chart created in "./compose/" - -$ tree compose/ -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. It's compatible with both Helm V2 and Helm V3. +A full list of these options can be found on `kompose convert --help`. ## Labels -`kompose` supports Kompose-specific labels within the `compose.yml` file to -explicitly define the generated resources' behavior upon conversion, like Service, PersistentVolumeClaim... - -The currently supported options are: - -| Key | Value | -|-----------------------------------------------------|--------------------------------------------------------------------------------------| -| kompose.controller.port.expose | defines whether to expose container to host or not (It has security concerns, not recommended) | -| 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 / statefulset | -| 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 | -| kompose.service.external-traffic-policy | 'cluster', 'local', '' | -| kompose.security-context.fsgroup | kubernetes pod security group fsgroup | -| kompose.volume.sub-path | kubernetes volume mount subpath | -| kompose.cronjob.schedule | kubernetes cronjob schedule (for example: '1 * * * *') | -| kompose.cronjob.concurrency_policy | 'Forbid' / 'Allow' / 'Never' / '' | -| kompose.cronjob.backoff_limit | kubernetes cronjob backoff limit (for example: '6') | -| kompose.init.containers.name | kubernetes init container name | -| kompose.init.containers.image | kubernetes init container image | -| kompose.init.containers.command | kubernetes init container commands | -| kompose.hpa.replicas.min | defines Horizontal Pod Autoscaler minimum number of pod replicas | -| kompose.hpa.replicas.max | defines Horizontal Pod Autoscaler maximum number of pod replicas | -| kompose.hpa.cpu | defines Horizontal Pod Autoscaler cpu utilization trigger | -| kompose.hpa.memory | defines Horizontal Pod Autoscaler memory utilization trigger | - -**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" +`kompose` supports Kompose-specific labels within the `compose.yaml` file to get you the rest of the way there. + +Labels are an important kompose concept as they allow you to add Kubernetes modifications without having to edit the YAML afterwards. For example, adding an init container, or a custom readiness check. + +| Key / Value | Description / Example | +|-----|-------------| +| [`kompose.controller.port.expose`](#komposecontrollerportexpose) | Expose as hostPort on the controller (not recommended) | +| `Boolean` | `false` | +| [`kompose.controller.type`](#komposecontrollertype) | Type of the controller | +| `String` | `deployment`, `daemonset`, `replicationcontroller`, `statefulset` | +| [`kompose.cronjob.backoff_limit`](#komposecronjobbackoff_limit) | Number of retries before marked as failed | +| `Integer` | `6` | +| [`kompose.cronjob.concurrency_policy`](#komposecronjobconcurrency_policy) | Handling of concurrent jobs | +| `String` | `Forbid`, `Allow`, `Never` | +| [`kompose.cronjob.schedule`](#komposecronjobschedule) | Schedule | +| `String` | `1 * * * *` | +| [`kompose.hpa.cpu`](#komposehpacpu) | CPU utilization percentage that triggers autoscaling | +| `Percentage` | `50%` | +| [`kompose.hpa.memory`](#komposehpamemory) | Memory utilization threshold that triggers autoscaling | +| `String` | `200Mi` | +| [`kompose.hpa.replicas.max`](#komposehpareplicasmax) | Max pod replicas for Horizontal Pod Autoscaler | +| `Integer` | `10` | +| [`kompose.hpa.replicas.min`](#komposehpareplicasmin) | Min pod replicas for Horizontal Pod Autoscaler | +| `Integer` | `2` | +| [`kompose.image-pull-policy`](#komposeimage-pull-policy) | Policy for pulling images | +| `String` | `Always`, `IfNotPresent`, `Never` | +| [`kompose.image-pull-secret`](#komposeimage-pull-secret) | Secret to be used for pulling images from a private registry | +| `String` | `myregistrykey` | +| [`kompose.init.containers.command`](#komposeinitcontainerscommand) | Command to be executed | +| `Array` | `["printenv"]` | +| [`kompose.init.containers.image`](#komposeinitcontainersimage) | Image to be used | +| `String` | `busybox` | +| [`kompose.init.containers.name`](#komposeinitcontainersname) | Name assigned | +| `String` | `init-mydb` | +| [`kompose.security-context.fsgroup`](#komposesecurity-contextfsgroup) | Filesystem group ID for the pods' volumes | +| `Integer` | `1001` | +| [`kompose.service.external-traffic-policy`](#komposeserviceexternal-traffic-policy) | Policy to route external traffic | +| `String` | `cluster`, `local` | +| [`kompose.service.expose`](#komposeserviceexpose) | Creates a Ingress or Route. Accepts domain or 'true' for auto-generating a domain. | +| `String` | `true,domain1.com,domain2.com` | +| [`kompose.service.expose.ingress-class-name`](#komposeserviceexposeingress-class-name) | Ingress class to be used for exposing services | +| `String` | `nginx` | +| [`kompose.service.expose.tls-secret`](#komposeserviceexposetls-secret) | TLS secret for securing ingress | +| `String` | `my-tls-secret` | +| [`kompose.service.group`](#komposeservicegroup) | Label to group multiple containers in a single pod | +| `String` | `mygroup` | +| [`kompose.service.healthcheck.liveness.http_get_path`](#komposeservicehealthchecklivenesshttp_get_path) | HTTP GET path for liveness probe | +| `String` | `/health` | +| [`kompose.service.healthcheck.liveness.http_get_port`](#komposeservicehealthchecklivenesshttp_get_port) | HTTP GET port for liveness probe | +| `Integer` | `8080` | +| [`kompose.service.healthcheck.liveness.tcp_port`](#komposeservicehealthchecklivenesstcp_port) | TCP socket port for liveness probe | +| `Integer` | `3306` | +| [`kompose.service.healthcheck.readiness.disable`](#komposeservicehealthcheckreadinessdisable) | Whether to disable the readiness probe | +| `Boolean` | `true` | +| [`kompose.service.healthcheck.readiness.http_get_path`](#komposeservicehealthcheckreadinesshttp_get_path) | HTTP GET path for readiness probe | +| `String` | `/ready` | +| [`kompose.service.healthcheck.readiness.http_get_port`](#komposeservicehealthcheckreadinesshttp_get_port) | HTTP GET port for readiness probe | +| `Integer` | `8081` | +| [`kompose.service.healthcheck.readiness.interval`](#komposeservicehealthcheckreadinessinterval) | Interval between readiness checks | +| `Duration` | `10s` | +| [`kompose.service.healthcheck.readiness.retries`](#komposeservicehealthcheckreadinessretries) | Number of times readiness probe should retry before failing | +| `Integer` | `3` | +| [`kompose.service.healthcheck.readiness.start_period`](#komposeservicehealthcheckreadinessstart_period) | Initial delay before starting the readiness probe | +| `Duration` | `30s` | +| [`kompose.service.healthcheck.readiness.tcp_port`](#komposeservicehealthcheckreadinesstcp_port) | TCP socket port for readiness probe | +| `Integer` | `3307` | +| [`kompose.service.healthcheck.readiness.test`](#komposeservicehealthcheckreadinesstest) | Command or script run by the readiness probe | +| `Array` | `["CMD", "echo", "OK"]` | +| [`kompose.service.healthcheck.readiness.timeout`](#komposeservicehealthcheckreadinesstimeout) | Timeout for a single readiness probe | +| `Duration` | `5s` | +| [`kompose.service.nodeport.port`](#komposeservicenodeportport) | Specific port number to be used as NodePort | +| `Integer` | `30000` | +| [`kompose.service.type`](#komposeservicetype) | Type of service | +| `String` | `nodeport`, `clusterip`, `loadbalancer`, `headless` | +| [`kompose.volume.size`](#komposevolumesize) | Size of the volume | +| `String` | `1Gi` | +| [`kompose.volume.storage-class-name`](#komposevolumestorage-class-name) | StorageClassName for provisioning volumes | +| `String` | `standard` | +| [`kompose.volume.sub-path`](#komposevolumesub-path) | Subpath inside the mounted volume | +| `String` | `/data` | +| [`kompose.volume.type`](#komposevolumetype) | Type of Kubernetes volume | +| `String` | `configMap`, `persistentVolumeClaim`, `emptyDir`, `hostPath` | + +### kompose.controller.port.expose + +```yaml services: - nginx: - image: nginx - dockerfile: foobar - build: ./foobar - cap_add: - - ALL - container_name: foobar + web: + image: wordpress:latest + ports: + - '80:80' labels: - kompose.service.type: nodeport + kompose.controller.expose.port: true ``` -- `kompose.service.group` defines the group of containers included in a single pod. - -For example: +### kompose.controller.type ```yaml -version: "3" - services: - nginx: - image: nginx - depends_on: - - logs + web: + image: wordpress:latest + ports: + - '80:80' labels: - - kompose.service.group=sidecar + kompose.controller.type: deployment +``` - logs: +### kompose.cronjob.backoff_limit + +```yaml +services: + cron-job: image: busybox - command: ["tail -f /var/log/nginx/access.log"] labels: - - kompose.service.group=sidecar + kompose.cronjob.backoff_limit: 3 ``` -- `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-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. - -For example: +### kompose.cronjob.concurrency_policy ```yaml -version: "2" services: - web: - image: tuna/docker-counter23 - ports: - - "5000:5000" - links: - - redis + periodic-task: + image: busybox labels: - kompose.service.expose: "counter.example.com,foobar.example.com" - kompose.service.expose.tls-secret: "example-secret" - kompose.service.expose.ingress-class-name: "nginx" - redis: - image: redis:3.0 - ports: - - "6379" + kompose.cronjob.concurrency_policy: Forbid ``` -- `kompose.serviceaccount-name` defines the service account name to provide the credential info of the pod. - -For example: +### kompose.cronjob.schedule ```yaml -version: '3.4' services: - app: - image: python + cron-job: + image: busybox labels: - kompose.serviceaccount-name: "my-service" + kompose.cronjob.schedule: "*/5 * * * *" ``` -- `kompose.image-pull-secret` defines a kubernetes secret name for imagePullSecrets podspec field. - This secret will be used for pulling private images. - For example: +### kompose.hpa.cpu ```yaml -version: '2' services: - tm-service: - image: premium/private-image + web: + image: nginx labels: - kompose.image-pull-secret: "example-kubernetes-secret" + kompose.hpa.cpu: 80 ``` -- `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: +### kompose.hpa.memory ```yaml -version: '2' services: db: - image: postgres:10.1 + image: mysql labels: - kompose.volume.size: 1Gi - volumes: - - db-data:/var/lib/postgresql/data + kompose.hpa.memory: 512Mi ``` -- `kompose.volume.storage-class-name` defines the requests storage's class name in the PersistentVolumeClaim. - -For example: +### kompose.hpa.replicas.max ```yaml -version: '3' services: - db: - image: postgres:10.1 + api: + image: custom-api labels: - kompose.volume.storage-class-name: custom-storage-class-name - volumes: - - db-data:/var/lib/postgresql/data + kompose.hpa.replicas.max: 10 ``` -- `kompose.controller.type` defines which controller type should convert for this service - -For example: +### kompose.hpa.replicas.min +```yaml +services: + api: + image: custom-api + labels: + kompose.hpa.replicas.min: 2 ``` -web: - image: wordpress:4.5 - ports: - - '80' - environment: - WORDPRESS_AUTH_KEY: changeme - WORDPRESS_SECURE_AUTH_KEY: changeme - WORDPRESS_LOGGED_IN_KEY: changeme - WORDPRESS_NONCE_KEY: changeme - WORDPRESS_AUTH_SALT: changeme - WORDPRESS_SECURE_AUTH_SALT: changeme - WORDPRESS_LOGGED_IN_SALT: changeme - WORDPRESS_NONCE_SALT: changeme - WORDPRESS_NONCE_AA: changeme - restart: always - links: - - 'db:mysql' -db: - image: mysql:5.7 - environment: - MYSQL_ROOT_PASSWORD: password - restart: always - labels: - project.logs: /var/log/mysql - kompose.controller.type: daemonset -``` - -Service `web` will be converted to `Deployment` as default, service `db` will be converted to `DaemonSet` because of `kompose.controller.type` label. - -- `kompose.image-pull-policy` defines Kubernetes PodSpec imagePullPolicy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. -For example: +### kompose.image-pull-policy ```yaml -version: '2' services: example-service: image: example-image labels: - kompose.image-pull-policy: "Never" + kompose.image-pull-policy: "IfNotPresent" ``` -For example: +### kompose.image-pull-secret ```yaml -version: '2' services: - example-service: - image: example-image + private-service: + image: private-repo/image:tag labels: - kompose.service.healthcheck.liveness.http_get_path: /health/ping - kompose.service.healthcheck.liveness.http_get_port: 8080 - healthcheck: - interval: 10s - timeout: 10s - retries: 3 - start_period: 30s + kompose.image-pull-secret: "my-private-registry-key" ``` -- `kompose.service.healthcheck.liveness` defines Kubernetes [liveness HttpRequest](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request), If you use healthcheck without liveness labels, have to define `test` in healcheck it's work to Kubernetes [liveness command](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes) +### kompose.init.containers.command + +```yaml +services: + init-service: + image: busybox + labels: + kompose.init.containers.command: ["echo", "Initializing..."] +``` -For example: +### kompose.init.containers.image ```yaml -version: '2' services: - example-service: - image: example-image + init-service: + image: busybox labels: - kompose.service.healthcheck.readiness.test: CMD curl -f "http://localhost:8080/health/ping" - kompose.service.healthcheck.readiness.interval: 10s - kompose.service.healthcheck.readiness.timeout: 10s - kompose.service.healthcheck.readiness.retries: 3 - kompose.service.healthcheck.readiness.start_period: 30s + kompose.init.containers.image: busybox ``` -- `kompose.service.healthcheck.readiness` defines Kubernetes [readiness](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes) +### kompose.init.containers.name -- `kompose.service.external-traffic-policy` defines Kubernetes Service [external traffic policy.](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip). +```yaml +services: + init-service: + image: busybox + labels: + kompose.init.containers.name: "initial-setup" +``` -For example: +### kompose.security-context.fsgroup ```yaml -version: "3.3" +services: + secured-service: + image: nginx + labels: + kompose.security-context.fsgroup: 2000 +``` + +### kompose.service.external-traffic-policy +```yaml services: front-end: image: quay.io/kompose/web ports: - 8080:8080 labels: - kompose.service.expose: lb kompose.service.external-traffic-policy: local - kompose.service.type: loadbalancer ``` -- `kompose.security-context.fsgroup` defines Kubernetes Pod [security context FsGroup.](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). +### kompose.service.expose + +```yaml +services: + web-app: + image: nginx + ports: + - 80:80 + labels: + kompose.service.expose: "example.com" +``` -For example: +### kompose.service.expose.ingress-class-name ```yaml -version: '3.8' +services: + web: + image: nginx + ports: + - 80:80 + labels: + kompose.service.expose.ingress-class-name: "nginx" +``` + +### kompose.service.expose.tls-secret +```yaml services: - pgadmin: + web: image: nginx + ports: + - 443:443 labels: - kompose.security-context.fsgroup: 1001 + kompose.service.expose.tls-secret: "my-ssl-secret" ``` -- `kompose.volume.sub-path` defines Kubernetes Container [VolumeMounts Subpath](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath). +### kompose.service.group -For example: +```yaml +version: "3" + +services: + nginx: + image: nginx + depends_on: + - logs + labels: + - kompose.service.group=sidecar + + logs: + image: busybox + command: ["tail -f /var/log/nginx/access.log"] + labels: + - kompose.service.group=sidecar +``` + +### kompose.service.healthcheck.liveness.http_get_path ```yaml -version: '3.8' +services: + web: + image: custom-web + ports: + - "8080:8080" + labels: + kompose.service.healthcheck.liveness.http_get_path: /health +``` +### kompose.service.healthcheck.liveness.http_get_port + +```yaml services: - pgadmin: - image: postgres + web: + image: custom-web + ports: + - "8080:8080" labels: - kompose.volume.sub-path: pg-data + kompose.service.healthcheck.liveness.http_get_port: 8080 ``` -- `kompose.init.containers.name` is used to specify the name of the Init Containers for a Pod [Init Container Name](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) +### kompose.service.healthcheck.liveness.tcp_port -For example: +```yaml +services: + db: + image: mysql + ports: + - "3306:3306" + labels: + kompose.service.healthcheck.liveness.tcp_port: 3306 +``` + +### kompose.service.healthcheck.readiness.disable ```yaml -version: '3' services: - example-service: - image: example-image + web: + image: custom-web labels: - kompose.init.containers.name: "initcontainername" + kompose.service.healthcheck.readiness.disable: true ``` -- `kompose.init.containers.image` defines image to use for the Init Containers [Init Container Image](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) +### kompose.service.healthcheck.readiness.http_get_path + +```yaml +services: + web: + image: custom-web + labels: + kompose.service.healthcheck.readiness.http_get_path: /ready +``` -For example: +### kompose.service.healthcheck.readiness.http_get_port ```yaml -version: '3' services: - example-service: - image: example-image + web: + image: custom-web labels: - kompose.init.containers.image: perl + kompose.service.healthcheck.readiness.http_get_port: 8081 ``` +### kompose.service.healthcheck.readiness.interval -- `kompose.init.containers.command` defines the command that the Init Containers will run after they are started [Init Container Command](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) +```yaml +services: + web: + image: custom-web + labels: + kompose.service.healthcheck.readiness.interval: 10s +``` -For example: +### kompose.service.healthcheck.readiness.retries ```yaml -version: '3' services: - example-service: - image: example-image + web: + image: custom-web labels: - kompose.init.containers.command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"] - kompose.init.containers.image: perl + kompose.service.healthcheck.readiness.retries: 3 ``` +### kompose.service.healthcheck.readiness.start_period -- `kompose.hpa.replicas.min` defines the floor for the number of replicas that the HPA can scale down to during a scaling event. Default value is set to 1. This means that, regardless of the load on the system, the HPA will always maintain at least one replica. More info: [HPA Min Replicas](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics). +```yaml +services: + web: + image: custom-web + labels: + kompose.service.healthcheck.readiness.start_period: 30s +``` -For example: +### kompose.service.healthcheck.readiness.tcp_port ```yaml services: - pgadmin: - image: postgres + db: + image: mysql labels: - kompose.hpa.replicas.min: 1 + kompose.service.healthcheck.readiness.tcp_port: 3307 ``` -- `kompose.hpa.replicas.max` defines the upper limit for the number of replicas that the HPA can create during a scaling event. Default value is set to 3. This default value serves as a safeguard, providing a conservative starting point for your HPA configuration. More info: [HPA Max Replicas](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics). +### kompose.service.healthcheck.readiness.test + +```yaml +services: + web: + image: custom-web + labels: + kompose.service.healthcheck.readiness.test: ["CMD", "curl", "-f", "http://localhost:8081/ready"] +``` -For example: +### kompose.service.healthcheck.readiness.timeout ```yaml services: - pgadmin: - image: postgres + web: + image: custom-web labels: - kompose.hpa.replicas.max: 10 + kompose.service.healthcheck.readiness.timeout: 5s ``` -- `kompose.hpa.cpu` defines % cpu utilization that triggers to scale the number of pods. It is represented as a percentage of a resource. Default value is set to 50. This default value serves as a safeguard, providing a conservative starting point for your HPA configuration. More info: [HPA CPU Utilization](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics). +### kompose.service.nodeport.port -For example: +```yaml +services: + web: + image: nginx + ports: + - "30000:80" + labels: + kompose.service.nodeport.port: 30000 +``` + +### kompose.service.type ```yaml services: - pgadmin: - image: postgres + web: + image: nginx + ports: + - "80:80" + labels: + kompose.service.type: nodeport +``` + +### kompose.volume.size + +```yaml +services: + db: + image: postgres:10.1 labels: - kompose.hpa.cpu: 50 + kompose.volume.size: 1Gi + volumes: + - db-data:/var/lib/postgresql/data ``` -- `kompose.hpa.memory` defines memory utilization that triggers to scale the number of pods. It is represented as a percentage of a resource. Default value is set to 70. This default value serves as a safeguard, providing a conservative starting point for your HPA configuration. More info: [HPA Memory Utilization](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics). +### kompose.volume.storage-class-name -For example: +```yaml +services: + db: + image: postgres:10.1 + labels: + kompose.volume.storage-class-name: custom-storage-class-name + volumes: + - db-data:/var/lib/postgresql/data +``` + +### kompose.volume.sub-path ```yaml services: pgadmin: image: postgres labels: - kompose.hpa.memory: 50 + kompose.volume.sub-path: pg-data ``` -## Restart +### kompose.volume.type -If you want to create normal pods without controller you can use `restart` construct of compose to define that. Follow table below to see what happens on the `restart` value. +```yaml +services: + db: + image: postgres + labels: + kompose.volume.type: persistentVolumeClaim + volumes: + - db-data:/var/lib/postgresql/data +``` + +## Restart Policy + +If you want to create normal pods without a controller you can use the `restart` construct of compose to define that. Follow the table below to see what happens on the `restart` value. | `compose` `restart` | object created | Pod `restartPolicy` | |---------------------|-------------------|---------------------| @@ -578,9 +575,9 @@ If you want to create normal pods without controller you can use `restart` const | `on-failure` | Pod / CronJob | `OnFailure` | | `no` | Pod / CronJob | `Never` | -**Note**: controller object could be `deployment` or `replicationcontroller`, etc. +**Note**: controller object could be `deployment`, `replicationcontroller`, etc. -For e.g. `pival` service will become pod down here. This container calculated value of `pi`. +For example, the `pival` service will become a pod down here. This container calculated the value of `pi`. ```yaml version: '2' @@ -592,7 +589,7 @@ services: restart: "on-failure" ``` -For e.g. `pival` service will become cronjob down here. This container calculated value of `pi` every minute. +For example, the `pival` service will become a cron job down here. This container calculated the value of `pi` every minute. ```yaml version: '2' @@ -608,28 +605,23 @@ services: kompose.cronjob.backoff_limit: "0" ``` -#### Warning about Deployment Config's +#### Warning about Deployment Configs If the 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. -If the Compose file has service name with `_` or `.` in it (eg.`web_service` or `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. +If the Compose file has a service name with `_` or `.` in it (e.g., `web_service` or `web.service`), then it will be replaced by `-` and the service name will be renamed accordingly (e.g., `web-service`). Kompose does this because "Kubernetes" doesn't allow `_` in object names. -Please note that changing service name might break some `compose` files. +Please note that changing the service name might break some `compose` files. -## Network policies generation -[Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies) are not generated by default, because it's not mandatory to deploy your application. However, it's one of the best practices when it comes to deploy secure applications on top of Kubernetes. -To generate network policies, all you need is to use the `--generate-network-policies` flag. - -## Build and push image +## Building and Pushing Images If the 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. -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 a custom registry by specifying `--push-image-registry`, which will override the registry from the image name. -### Authentication on registry +### Authentication on Registry Kompose uses the docker authentication from file `$DOCKER_CONFIG/config.json`, `$HOME/.docker/config.json`, and `$HOME/.dockercfg` after `docker login`. @@ -637,7 +629,7 @@ Kompose uses the docker authentication from file `$DOCKER_CONFIG/config.json`, ` 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. +- remove `credsStore` from the `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. @@ -645,8 +637,9 @@ Now `config.json` should contain base64 encoded passwords, then push image shoul 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. ### Custom Build and Push + If you want to customize the build and push processes and use another containers solution than Docker, Kompose offers you the possibility to do that. You can use `--build-command` and `--push-command` flags to achieve that. -e.g: `kompose -f convert --build-command 'whatever command --you-use' --push-command 'whatever command --you-use'` +e.g: `kompose -f convert --build-command 'whatever command --you-use' --push-command 'whatever command --you-use'` \ No newline at end of file