Skip to content

docs: add dev selector #2022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FabianKramm merged 1 commit into from
Apr 1, 2022
Merged

docs: add dev selector #2022

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 81 additions & 55 deletions docs/pages/configuration/dev/container/selector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,68 +5,96 @@ sidebar_label: selector


## Pod/Container Selection
The following config options are needed to determine the container which the file synchronization should be established to:
The following config options are needed to determine the pod which DevSpace should select
- [`imageSelector`](#imageselector)
- [`labelSelector`](#labelselector)
- [`containerName`](#containername)
- [`container`](#container)
- [`namespace`](#namespace)

:::info Auto Reconnect
If the sync is unable to establish a connection to the selected container or loses it after starting the sync, DevSpace will try to restart the sync several times.
If one of the services is unable to establish a connection to the selected container or loses it after starting the sync, DevSpace will try to restart the dev services.
:::

### `imageSelector`
<FragmentImageSelector />
The `imageSelector` option expects a string that specifies an image (e.g. `my-registry.com/lib/my-image:tag`, `alpine:latest` or `nginx`) to select a target pod and container with it. The newest running pod that has a container which matches this image will be selected by DevSpace.

In addition, you can also reference images from the `images` section in the `imageSelector` with:
- If the image in `imageSelector` matches a `images.*.image`, DevSpace will automatically append the latest built tag during runtime to the `imageSelector`.
- You can also let DevSpace resolve the target image and tag by using runtime variables `${runtime.images.IMAGE_NAME}`, `${runtime.images.IMAGE_NAME.image}` or `${runtime.images.IMAGE_NAME.tag}`

For example:
```yaml
images:
app:
image: my-registry.com/lib/my-image

dev:
...
# DevSpace will search for the newest pod with a container that
# uses my-registry.com/lib/other-image:latest
imageSelector: my-registry.com/lib/other-image:latest
# DevSpace will search for the newest pod with a container that
# uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
imageSelector: my-registry.com/lib/my-image
# DevSpace will search for the newest pod with a container that
# uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
imageSelector: ${runtime.images.app}
# DevSpace will search for the newest pod with a container that
# uses my-registry.com/lib/my-image:custom-tag
imageSelector: ${runtime.images.app.image}:custom-tag
# DevSpace will search for the newest pod with a container that
# uses my-registry.com/lib/my-image:xxxxx (latest built tag by DevSpace)
imageSelector: ${runtime.images.app.image}:${runtime.images.app.tag}
# DevSpace will search for the newest pod with a container that
# uses the image of app of dependency dep1 with the latest built tag by DevSpace
imageSelector: ${runtime.dependencies.dep1.images.app.image}:${runtime.dependencies.dep1.images.app.tag}
```

#### Example: Select Container by Image
```yaml
vars:
- name: backend-image
value: john/devbackend
- name: backend-debugger-image
value: john/debugger
BACKEND_IMAGE: john/devbackend
BACKEND_DEBUGGER_IMAGE: john/debugger

images:
backend:
image: ${backend-image}
image: ${BACKEND_IMAGE}
backend-debugger:
image: ${backend-debugger-image}
image: ${BACKEND_DEBUGGER_IMAGE}

deployments:
- name: app-backend
helm:
componentChart: true
values:
containers:
- name: container-0
image: ${backend-image}
- name: container-1
image: ${backend-debugger-image}
app-backend:
helm:
values:
containers:
- name: container-0
image: ${BACKEND_IMAGE}
- name: container-1
image: ${BACKEND_DEBUGGER_IMAGE}

dev:
sync:
- imageSelector: ${backend-image}
excludePaths:
- node_modules/
- logs/
- imageSelector: ${backend-debugger-image}
localSubPath: ./debug-logs
containerPath: /logs
my-dev-1:
imageSelector: ${BACKEND_IMAGE}
sync:
- path: ./
my-dev-2:
imageSelector: ${BACKEND_DEBUGGER_IMAGE}
sync:
- path: ./debug-logs:/logs
```
**Explanation:**
- The above example defines two images that can be used as `imageSelector`: `john/devbackend` or `john/debugger`
- The deployment starts two containers and each of them uses an image from the `images` section.
- The `imageSelector` option of the first sync configuration in the `dev.sync` section references the same image as `images.backend`. That means DevSpace would select the first container for file synchronization, that would match `john/devbackend:tag(backend)`, where `tag(backend)` is the last built tag of `images.backend`
- The first sync configuration does not define `localSubPath`, so it defaults to the project's root directory (location of `devspace.yaml`).
- The first sync configuration does not define `containerPath`, so it defaults to the container's working directory (i.e. `WORKDIR`).
- The `imageSelector` option of the second sync configuration in the `dev.sync` section references the same image as `images.backend-debugger`. That means DevSpace would select the second container for file synchronization, as this container uses the `image: john/debugger` which belongs to the `backend-debugger` image as defined in the `images` section.
- The `imageSelector` option of the first sync configuration in the `dev.*.sync` section references the same image as `images.backend`. That means DevSpace would select the first container for file synchronization, that would match `john/devbackend:tag(backend)`, where `tag(backend)` is the last built tag of `images.backend`
- The `imageSelector` option of the second sync configuration in the `dev.*.sync` section references the same image as `images.backend-debugger`. That means DevSpace would select the second container for file synchronization, as this container uses the `image: john/debugger` which belongs to the `backend-debugger` image as defined in the `images` section.

In consequence, the following sync processes would be started when using the above config example assuming the local project root directoy `/my/project/`:

1. `localhost:/my/project/` forwards to `container-0:$WORKDIR` **\***
2. `localhost:/my/project/debug-logs/` forwards to `container-1:/logs`

**\* Changes on either side (local and container filesystem) that occur within the sub-folders `node_modules/` and `logs/` would be ingored.**

### `labelSelector`
<FragmentLabelSelector />
The `labelSelector` option expects a key-value map of strings with Kubernetes labels. This can be used to select the correct target pod with labels instead of the image name like `imageSelector` or `imageName`. If the pod you want to select has multiple containers, make sure to use `container` as well.

#### Example: Select Container by Label
```yaml {18-21}
Expand All @@ -75,36 +103,37 @@ images:
image: john/devbackend
backend-debugger:
image: john/debugger

deployments:
- name: app-backend
helm:
componentChart: true
values:
containers:
- name: container-0
image: john/devbackend
- name: container-1
image: john/debugger
app-backend:
helm:
values:
containers:
- name: container-0
image: john/devbackend
- name: container-1
image: john/debugger

dev:
sync:
- labelSelector:
my-dev:
labelSelector:
app.kubernetes.io/name: devspace-app
app.kubernetes.io/component: app-backend
custom-label: custom-label-value
containerName: container-0
localSubPath: ./src
containerPath: /app/src
container: container-0
sync:
- path: ./src:/app/src
```
**Explanation:**
- The `labelSelector` would select the pod created for the component deployment `app-backend`.
- Because the selected pod has two containers, we also need to specify the `containerName` option which defines the container that should be used for the file synchronization.
- Because the selected pod has two containers, we also need to specify the `container` option which defines the container that should be used for the file synchronization.


### `containerName`
The `containerName` option expects a string with a container name. This option is used to decide which container should be selected when using the `labelSelector` option because `labelSelector` selects a pod and a pod can have multiple containers.
### `container`
The `container` option expects a string with a container name. This option is used to decide which container should be selected when using the `labelSelector` option because `labelSelector` selects a pod and a pod can have multiple containers.

:::info
The `containerName` option is not required if the pod you are selecting using `imageName` or `labelSelector` has only one container.
The `container` option is not required if the pod you are selecting using `imageSelector` or `labelSelector` has only one container.
:::

#### Example
Expand All @@ -117,6 +146,3 @@ The `namespace` option expects a string with a Kubernetes namespace used to sele
:::warning
It is generally **not** needed (nor recommended) to specify the `namespace` option because by default, DevSpace uses the default namespace of your current kube-context which is usually the one that has been used to deploy your containers to.
:::


<br/>