Skip to content

Commit 0b65d97

Browse files
FabianKrammFabianKramm
committed
docs: add profiles documentation
1 parent 5b42c6e commit 0b65d97

6 files changed

Lines changed: 541 additions & 0 deletions

File tree

‎docs/pages/configuration/profiles/README.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Config Profiles
3+
sidebar_label: Basics
4+
---
5+
6+
import FragmentInfoPrintConfig from '../../_partials/tip-print-config.mdx';
7+
import FragmentApplyMultiple from '../../_partials/profiles-apply-multiple.mdx';
8+
9+
DevSpace allows you to define different profiles for different use cases (e.g. working on different services in the same project, starting certain debugging environments) or for different deployment targets (e.g. dev, staging production).
10+
11+
Profiles allow you to define:
12+
- [`replace`](../../configuration/profiles/replace.mdx) statements to override entire sections of the config.
13+
- [`merge`](../../configuration/profiles/merge.mdx) patches ([JSON Merge Patch, RFC 7386](https://tools.ietf.org/html/rfc7386)) to change specific parts of the config.
14+
- [`patches`](../../configuration/profiles/patches.mdx) ([JSON Patch, RFC 6902](https://tools.ietf.org/html/rfc6902)) to modify certain paths in the config.
15+
16+
:::note Combine several strategies
17+
It is possible to use several strategies together within one profile. The execution order inside a single profile is:
18+
1. `replace`
19+
2. `merge`
20+
3. `patches`
21+
22+
You can also apply multiple profiles through the `--profile` flag
23+
:::
24+
25+
:::tip Debug Profiles
26+
27+
<FragmentInfoPrintConfig/>
28+
29+
:::
30+
31+
A profile has to be configured in the `profiles` section of the `devspace.yaml`.
32+
```yaml {15-25}
33+
images:
34+
backend:
35+
image: john/devbackend
36+
backend-debugger:
37+
image: john/debugger
38+
deployments:
39+
backend:
40+
helm:
41+
values:
42+
containers:
43+
- image: john/devbackend
44+
- image: john/debugger
45+
profiles:
46+
- name: production
47+
patches:
48+
- op: replace
49+
path: images.backend.image
50+
value: john/prodbackend
51+
- op: remove
52+
path: deployments.backend.helm.values.containers[1]
53+
- op: add
54+
path: deployments.backend.helm.values.containers
55+
value:
56+
image: john/cache
57+
```
58+
59+
## Useful Commands
60+
61+
### `devspace print -p [profile]`
62+
63+
<FragmentInfoPrintConfig/>
64+
65+
<FragmentApplyMultiple/>
66+
67+
### `devspace list profiles`
68+
To get a list of available profiles, you can run this command:
69+
```bash
70+
devspace list profiles
71+
```
72+
73+
### `devspace use profile [profile]`
74+
To permanently switch to a different profile, you can run this command:
75+
```bash
76+
devspace use profile [PROFILE_NAME]
77+
```
78+
79+
:::note
80+
Permanently switching to a profile means that all future commands (e.g. `devspace deploy` or `devspace dev`) will be executed using this profile until the user [resets the profile](#devspace-use-profile---reset) (see below).
81+
:::
82+
83+
### `devspace use profile --reset`
84+
To permanently switch back to the default configuration (no profile replaces and patches active), you can run this command:
85+
```bash
86+
devspace use profile --reset
87+
```
88+
89+
### `devspace [deploy] -p [profile]`
90+
Most DevSpace commands support the `-p / --profile` flag. Using this flag, you can run a single command with a different profile without switching your profile permenantly:
91+
```bash
92+
devspace build -p [PROFILE_NAME]
93+
devspace deploy -p [PROFILE_NAME]
94+
devspace dev -p [PROFILE_NAME]
95+
devspace dev -i -p [PROFILE_NAME]
96+
```

‎docs/pages/configuration/profiles/activation.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: "Profiles: Activation"
3+
sidebar_label: activation
4+
---
5+
6+
The `activation` option is optional and allows you to activate a profile using regular expression matching of either Devspace or environment variables. An activation is configured with the profile it activates in `devspace.yaml`.
7+
8+
9+
#### Example: Defining a Profile Activation using `vars`
10+
```yaml {1-3,7-8}
11+
vars:
12+
- name: ENV
13+
default: development
14+
profiles:
15+
- name: production
16+
activation:
17+
- vars:
18+
ENV: production
19+
patches:
20+
- op: replace
21+
path: images.backend.image
22+
value: john/prodbackend
23+
```
24+
The `production` profile would be activated when the Devspace variable `ENV` has value `production`. In this example, it has a default value of `development`, so it is not activated unless you override the value using `--var ENV=production`
25+
26+
#### Example: Defining a Profile Activation using Environment Variables
27+
```yaml {3-5}
28+
profiles:
29+
- name: production
30+
activation:
31+
- env:
32+
ENV: "production"
33+
patches:
34+
- op: replace
35+
path: images.backend.image
36+
value: john/prodbackend
37+
```
38+
The `production` profile would be activated when the environment variable `ENV` has value `production`:
39+
40+
#### Example: Regular Expression Activation
41+
```yaml {3-5}
42+
profiles:
43+
- name: production
44+
activation:
45+
- env:
46+
ENV: "prod-\d+"
47+
patches:
48+
- op: replace
49+
path: images.backend.image
50+
value: john/prodbackend
51+
```
52+
The profile `production` would be activated when the environment variable `ENV` matches the regular expression `prod-\d+`. This can be useful for matching environment variables that have dynamic values. Regular expressions will have start of string (`^`) and end of string (`$`) anchors added automatically to avoid unexpected substring matching.
53+
54+
#### Example: Matching All
55+
When multiple `env` or `vars` name/expression pairs are specified in the same activation, all expressions must match to activate the profile. For example, the `production` profile is activated when the environment variable `CI` is `true` and the Devspace variable `ENV` is `development`:
56+
```yaml {3-7}
57+
profiles:
58+
- name: production
59+
activation:
60+
- env:
61+
CI: "true"
62+
vars:
63+
ENV: "development"
64+
patches:
65+
- op: replace
66+
path: images.backend.image
67+
value: john/devbackend
68+
```
69+
70+
:::note Combining `env` and `vars`
71+
While possible to activate profiles using environment variables and Devspace variables, `vars` can also be populated through environment variables. In the above example, we could have also defined `CI` as a Devspace variable with `source: env` and only used `vars` in the activation.
72+
:::
73+
74+
#### Example: Matching Any
75+
When `env` or `vars` are used in multiple activations, the profile is activated when any expression matches. In this example, the `production` profile is activated when either match their expressions:
76+
```yaml {3-7}
77+
profiles:
78+
- name: production
79+
activation:
80+
- env:
81+
CI: "true"
82+
- vars:
83+
ENV: "development"
84+
patches:
85+
- op: replace
86+
path: images.backend.image
87+
value: john/devbackend
88+
```
89+
90+
### Dependency Activations
91+
When `dependencies` are referenced from a `devspace.yaml`, the dependency's profile activations will also be evaluated. In this example, any profile activations in `./component-1/devspace.yaml` or `./component-2/devspace.yaml` would be evaluated.
92+
93+
```yaml
94+
dependencies:
95+
- name: component-1
96+
source:
97+
path: ./component-1
98+
- name: component-2
99+
source:
100+
path: ./component-2
101+
```
102+
103+
#### Example: Disable Activations by Dependency
104+
The `disableProfileActivation` option can be used to disable profile activations for specific dependencies. In the following example, the activations for `./component-1/devspace.yaml` would be ignored, while the activations in `./component-2/devspace.yaml` would be evaluated:
105+
```yaml {5}
106+
dependencies:
107+
- name: component-1
108+
source:
109+
path: ./component-1
110+
disableProfileActivation: true
111+
- name: component-2
112+
source:
113+
path: ./component-2
114+
```
115+
116+
### Disable Activations Globally
117+
The `--disable-profile-activation` flag can be used to disable all profile activations, including those specifed within each dependency's `devspace.yaml`.

‎docs/pages/configuration/profiles/merge.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Profiles: Merge"
3+
sidebar_label: merge
4+
---
5+
6+
Merge patches are a way to perform specific overrides to the configuration without having to create a completely separate config file. Patch functionality follows [JSON Merge Patch, RFC 7386](https://tools.ietf.org/html/rfc7386) semantics.
7+
8+
### Example
9+
10+
Merge patches are ideal for reflecting changes between different environments, e.g. dev, staging and production.
11+
```yaml {16-30}
12+
images:
13+
backend:
14+
image: john/devbackend
15+
backend-debugger:
16+
image: john/debugger
17+
deployments:
18+
backend:
19+
helm:
20+
values:
21+
containers:
22+
- image: john/devbackend
23+
- image: john/debugger
24+
profiles:
25+
- name: production
26+
merge:
27+
images:
28+
# Change the backend image
29+
backend:
30+
image: john/prodbackend
31+
# Delete the backend-debugger image
32+
backend-debugger: null
33+
# Override deployments
34+
deployments:
35+
backend:
36+
helm:
37+
values:
38+
containers:
39+
- image: john/prodbackend
40+
```
41+
**Explanation:**
42+
- The above example defines 1 profile: `production`
43+
- When using the profile `production`, the config is merged with the given merge patch at `profiles[0].merge`.
44+
- Merge patches follow the rules as defined in [JSON Merge Patch, RFC 7386](https://tools.ietf.org/html/rfc7386):
45+
- Arrays are overridden
46+
- Objects are merged together
47+
- Keys that have a `null` value are removed from objects
48+
- The resulting config used in-memory when the profile `production` is used would look like this (you can check via `devspace print -p production`):
49+
50+
```yaml
51+
# In-Memory Config After Applying Merge Patches For Profile `production`
52+
images:
53+
backend:
54+
image: john/prodbackend
55+
deployments:
56+
backend:
57+
helm:
58+
values:
59+
containers:
60+
- image: john/prodbackend
61+
```
62+

0 commit comments

Comments
 (0)