|
1 | 1 | # create-preview |
| 2 | + |
| 3 | +The `create-preview` command can be used to create a preview environment in your *deployment config repository* for a pull request in you *app repository*. You can later easily delete this preview with the [`delete-preview` command](/gitopscli/commands/delete-preview/). |
| 4 | + |
| 5 | +You need to provide some additional configuration files in your repositories for this command to work. |
| 6 | + |
| 7 | +## Configuration |
| 8 | +### Preview Templates |
| 9 | + |
| 10 | +Your *deployment config repository* needs to contain a `.preview-templates` folder with the deployment configuration templates for every application you want to use this command for. |
| 11 | + |
| 12 | +For example you have to provide `.preview-templates/app-xy` for your app `app-xy`. The `create-preview` command simply copies this directory to the root of the repository. Only image tag and route host will be replaced in the preview version of the deployment. |
| 13 | + |
| 14 | +``` |
| 15 | +deployment-config-repo/ |
| 16 | +├── .preview-templates |
| 17 | +│ └── app-xy |
| 18 | +│ ├── values.yaml |
| 19 | +│ └── some-more-config-files-or-folders |
| 20 | +├── app-xy-production |
| 21 | +├── app-xy-staging |
| 22 | +├── app-xy-test |
| 23 | +└── app-xy-c7003101-preview <- This is how a created preview looks like |
| 24 | + ├── values.yaml <- image tag and route host are replaced in this one |
| 25 | + └── some-more-config-files-or-folders |
| 26 | +``` |
| 27 | + |
| 28 | +!!! info "Currently you have to specify image tag and route host in a `values.yaml` file. We are working on making this configurable in the future." |
| 29 | + |
| 30 | +### .gitops.config.yaml |
| 31 | + |
| 32 | +Make sure that your *app repository* contains a `.gitops.config.yaml` file. This file provides all information to |
| 33 | + |
| 34 | +1. find the *deployment config repository* |
| 35 | +2. locate the preview template for your app |
| 36 | +3. replace image tag and route host in the template |
| 37 | + |
| 38 | +```yaml |
| 39 | +deploymentConfig: |
| 40 | + # The organisation name of your deployment repo |
| 41 | + org: deployments |
| 42 | + # The repostiory name of your deployment repo |
| 43 | + repository: deployment-config-repo |
| 44 | + # The name of the application (name of the folder in `.preview-templates`) |
| 45 | + applicationName: app-xy |
| 46 | + |
| 47 | +previewConfig: |
| 48 | + route: |
| 49 | + host: |
| 50 | + # Your router host |
| 51 | + # {SHA256_8CHAR_BRANCH_HASH} gets replaced by a shortened hash of your feature branch name |
| 52 | + template: app.xy-{SHA256_8CHAR_BRANCH_HASH}.example.tld |
| 53 | + replace: |
| 54 | + # Paths that should be replaced in the `values.yaml` |
| 55 | + - path: image.tag |
| 56 | + variable: GIT_COMMIT # this is the latest git hash of the pull request branch |
| 57 | + - path: route.host |
| 58 | + variable: ROUTE_HOST # this is the resolved host.template from above |
| 59 | +``` |
| 60 | +
|
| 61 | +## Example |
| 62 | +
|
| 63 | +```bash |
| 64 | +gitopscli create-preview \ |
| 65 | + --git-provider-url https://bitbucket.baloise.dev \ |
| 66 | + --username $GIT_USERNAME \ |
| 67 | + --password $GIT_PASSWORD \ |
| 68 | + --git-user "GitOps CLI" \ |
| 69 | + --git-email "gitopscli@baloise.dev" \ |
| 70 | + --organisation "my-team" \ |
| 71 | + --repository-name "app-xy" \ |
| 72 | + --pr-id 4711 \ |
| 73 | + --branch "my-pr-branch" \ |
| 74 | + --create-pr \ |
| 75 | + --auto-merge |
| 76 | +``` |
| 77 | + |
| 78 | +!!! warning "The `--branch` parameter is currently used to locate the PR branch in the *app repository* as well as to create the change branch in the *deployment config repository*. This may lead to branch collisions in the config repository. Hence, the current behavior may be subject to change in the near future. [(Issue #40)](https://github.com/baloise-incubator/gitopscli/issues/40)" |
| 79 | + |
| 80 | +## Usage |
2 | 81 | ``` |
3 | 82 | usage: gitopscli create-preview [-h] --username USERNAME --password PASSWORD |
4 | 83 | [--git-user GIT_USER] [--git-email GIT_EMAIL] |
@@ -38,46 +117,3 @@ optional arguments: |
38 | 117 | -v [VERBOSE], --verbose [VERBOSE] |
39 | 118 | Verbose exception logging |
40 | 119 | ``` |
41 | | - |
42 | | -## Example |
43 | | -```bash |
44 | | -gitopscli create-preview \ |
45 | | ---git-provider-url https://bitbucket.baloise.dev \ |
46 | | ---username $GIT_USERNAME \ |
47 | | ---password $GIT_PASSWORD \ |
48 | | ---git-user "GitOpsCLI" \ |
49 | | ---git-email "gitopscli@baloise.dev" \ |
50 | | ---organisation "my-team" \ |
51 | | ---repository-name "my-app" \ |
52 | | ---branch "some-branch-name" \ |
53 | | ---create-pr \ |
54 | | ---pr-id 4711 \ |
55 | | ---auto-merge |
56 | | -``` |
57 | | - |
58 | | -## .gitops.config.yaml |
59 | | -Make sure that your application repository contains a `.gitops.config.yaml` file. |
60 | | - |
61 | | -```yaml |
62 | | -deploymentConfig: |
63 | | - # The organisation name of your deployment repo |
64 | | - org: DPL |
65 | | - # The repostiory name of your deployment repo |
66 | | - repository: incubator-non-prod |
67 | | - # The name of the application that is used in your deployment repo |
68 | | - applicationName: example |
69 | | - |
70 | | -previewConfig: |
71 | | - route: |
72 | | - host: |
73 | | - # your router host. |
74 | | - #{SHA256_8CHAR_BRANCH_HASH} gets replaced by a shortened hash of your feature branch name |
75 | | - template: example-{SHA256_8CHAR_BRANCH_HASH}.example.tld |
76 | | - replace: |
77 | | - # Paths that should be replaced |
78 | | - - path: image.tag |
79 | | - variable: GIT_COMMIT # this is the latest git hash of the PR branch |
80 | | - - path: route.host |
81 | | - variable: ROUTE_HOST # this is the resolved SHA256_8CHAR_BRANCH_HASH from above |
82 | | - |
83 | | -``` |
|
0 commit comments