1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
> :warning: **This project is no longer maintained** :warning:
# Compose on Kubernetes
[](https://circleci.com/gh/docker/compose-on-kubernetes/tree/master)
Compose on Kubernetes allows you to deploy Docker Compose files onto a
Kubernetes cluster.
# Table of contents
- [Get started](#get-started)
- [Developing Compose on Kubernetes](#developing-compose-on-kubernetes)
More documentation can be found in the [docs/](./docs) directory. This includes:
- [Architecture](./docs/architecture.md)
- [Mapping of stack to Kubernetes objects](./docs/mapping.md)
- [Compatibility matrix](./docs/compatibility.md)
# Get started
## Install Compose on Kubernetes on Docker Desktop
### Pre-requisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop).
- To install etcd using these instructions, you must have [Helm](https://helm.sh) in your client environment.
- [Download the Compose on Kubernetes installer](https://github.com/docker/compose-on-kubernetes/releases).
On Docker Desktop you will need to activate Kubernetes in the settings to use
Compose on Kubernetes.
### Create compose namespace
- Create a compose namespace by running `kubectl create namespace compose`
### Deploy etcd
Compose on Kubernetes requires an etcd instance (in addition to the kube-system etcd instance). Please follow [How to deploy etcd](./docs/deploy-etcd.md).
### Deploy Compose on Kubernetes
Run `installer-[darwin|linux|windows.exe] -namespace=compose -etcd-servers=http://compose-etcd-client:2379`.
## Check that Compose on Kubernetes is installed
You can check that Compose on Kubernetes is installed by checking for the
availability of the API using the command:
```console
$ kubectl api-versions | grep compose
compose.docker.com/v1beta1
compose.docker.com/v1beta2
```
## Deploy a stack
To deploy a stack, you can use the Docker CLI:
```console
$ cat docker-compose.yml
version: '3.3'
services:
db:
build: db
image: dockersamples/k8s-wordsmith-db
words:
build: words
image: dockersamples/k8s-wordsmith-api
deploy:
replicas: 5
web:
build: web
image: dockersamples/k8s-wordsmith-web
ports:
- "33000:80"
$ docker stack deploy --orchestrator=kubernetes -c docker-compose.yml hellokube
```
## Remove a stack
```
$ docker stack rm --orchestrator=kubernetes hellokube
```
# Developing Compose on Kubernetes
See the [contributing](./CONTRIBUTING.md) guides for how to contribute code.
## Pre-requisites
- `make`
- [Docker Desktop](https://www.docker.com/products/docker-desktop) (Mac or Windows) with engine version 18.09 or later
- Enable Buildkit by setting `DOCKER_BUILDKIT=1` in your environment
- Enable Kubernetes in Docker Desktop settings
### For live debugging
- Debugger capable of remote debugging with Delve API version 2
- Goland run-configs are pre-configured
## Debug quick start
### Debug install
To build and install a debug version of Compose on Kubernetes onto Docker
Desktop, you can use the following command:
```console
$ make -f debug.Makefile install-debug-images
```
This command:
- Builds the images with debug symbols
- Runs the debug installer:
- Installs debug versions of API server and Compose controller in the `docker` namespace
- Creates two debugging _LoadBalancer_ services (unused in this mode)
You can verify that Compose on Kubernetes is running with `kubectl` as follows:
```console
$ kubectl get all -n docker
NAME READY STATUS RESTARTS AGE
pod/compose-7c4dfcff76-jgwst 1/1 Running 0 59s
pod/compose-api-759f8dbb4b-2z5n2 2/2 Running 0 59s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/compose-api ClusterIP 10.98.42.151 <none> 443/TCP 59s
service/compose-api-server-remote-debug LoadBalancer 10.101.198.179 localhost 40001:31693/TCP 59s
service/compose-controller-remote-debug LoadBalancer 10.101.158.160 localhost 40000:31167/TCP 59s
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
deployment.apps/compose 1 1 1 1 59s
deployment.apps/compose-api 1 1 1 1 59s
NAME DESIRED CURRENT READY AGE
replicaset.apps/compose-7c4dfcff76 1 1 1 59s
replicaset.apps/compose-api-759f8dbb4b 1 1 1 59s
```
If you describe one of the deployments, you should see `*-debug:latest` in the
image name.
### Live debugging install
To build and install a live debugging version of Compose on Kubernetes onto
Docker Desktop, you can use the following command:
```console
$ make -f debug.Makefile install-live-debug-images
```
This command:
- Builds the images with debug symbols
- Sets the image entrypoint to run a [Delve server](https://github.com/derekparker/delve)
- Runs the debug installer
- Installs debug version of API server and Compose controller in the `docker` namespace
- Creates two debugging _LoadBalancer_ services
- `localhost:40000`: Compose controller
- `localhost:40001`: API server
- The API server and Compose controller only start once a debugger is attached
To attach a debugger you have multiple options:
- Use [GoLand](https://www.jetbrains.com/go/): configuration can be found in `.idea` of the repository
- Select the `Debug all` config, setup breakpoints and start the debugger
- Set your Delve compatible debugger to point to use `locahost:40000` and `localhost:40001`
- Using a terminal: `dlv connect localhost:40000` then type `continue` and hit enter
To verify that the components are installed, you can use the following command:
```console
$ kubectl get all -n docker
```
To verify that the API server has started, ensure that it has started logging:
```console
$ kubectl logs -f -n docker deployment.apps/compose-api compose
API server listening at: [::]:40000
ERROR: logging before flag.Parse: I1207 15:25:13.760739 11 plugins.go:158] Loaded 2 mutating admission controller(s) successfully in the following order: NamespaceLifecycle,MutatingAdmissionWebhook.
ERROR: logging before flag.Parse: I1207 15:25:13.763211 11 plugins.go:161] Loaded 1 validating admission controller(s) successfully in the following order: ValidatingAdmissionWebhook.
ERROR: logging before flag.Parse: W1207 15:25:13.767429 11 client_config.go:552] Neither --kubeconfig nor --master was specified. Using the inClusterConfig. This might not work.
ERROR: logging before flag.Parse: W1207 15:25:13.851500 11 genericapiserver.go:319] Skipping API compose.docker.com/storage because it has no resources.
ERROR: logging before flag.Parse: I1207 15:25:13.998154 11 serve.go:116] Serving securely on [::]:9443
```
To verify that the Compose controller has started, ensure that it is logging:
```console
kubectl logs -f -n docker deployment.apps/compose
API server listening at: [::]:40000
Version: v0.4.16-dirty
Git commit: b2e3a6b-dirty
OS/Arch: linux/amd64
Built: Fri Dec 7 15:18:13 2018
time="2018-12-07T15:25:19Z" level=info msg="Controller ready"
```
## Reinstall default
To reinstall the default Compose on Kubernetes on Docker Desktop, simply restart
your Kubernetes cluster. You can do this by deactivating and then reactivating
Kubernetes or by restarting Docker Desktop.
See the [contributing](./CONTRIBUTING.md) and [debugging](./DEBUGGING.md) guides.
# Deploying Compose on Kubernetes
- Guide for [Azure AKS](./docs/install-on-aks.md).
- Guide for [GKE](./docs/install-on-gke.md).
- Guide for [Microk8s](./docs/install-on-microk8s.md).
- Guide for [Minikube](./docs/install-on-minikube.md).
|
