github.com/opendevstack/tailor@v1.3.5-0.20220119161809-cab064e60a67/README.md (about)

     1  # Tailor
     2  
     3  Tailor is a tool to drive the configuration of your OpenShift resources via templates under version control. Any drift between your desired state (the YAML templates) and the current state (resources in the cluster) can be detected, reviewed and reconciled using a CLI interface. Tailor is required by other OpenDevStack repositories, but is fully standalone and may be used in completely different contexts. It uses `oc` commands under the hood, and is based on plain OpenShift templates.
     4  
     5  The main target of Tailor is OpenShift 3.11. Tailor also works against OpenShift 4, but it is recommended to transition to other tools, such as Helm or kustomize, which have become popular and work well against OpenShift 4. If you are interested how Tailor compares to those tools, please see [comparison to other tools](https://github.com/opendevstack/tailor#comparison-to-other-tools).
     6  
     7  ## Benefits of using infrastructure-as-code
     8  
     9  * Applications consisting of multiple resources or even whole namespaces can be created / cloned in one go based on configuration.
    10  * If resources are (accidentally) removed from the OpenShift cluster, they can be recreated from config.
    11  * Rollback of changes in the cluster is easy as configuration is under version control.
    12  * Visibility into which changes were made and by whom.
    13  
    14  ## Benefits of using Tailor over plain `oc` commands
    15  
    16  * Display and review drift before applying the desired state.
    17  * Support for encrypted secrets to avoid storing credentials in clear text in your repository.
    18  * Preserving the values of certain paths in "live" resources (e.g. values of immutable fields or any other field controlled by other means).
    19  * Simple interface which avoids having to stitch multiple commands together and massage their output to achieve the desired result.
    20  * Options can be stored in a `Tailorfile` to ease invocation and ensure consistency within teams.
    21  
    22  ## Installation
    23  
    24  The latest release is 1.3.4 and requires oc = v3.11. OpenShift 4 is not officially supported yet although 1.3.0 is known to work with OpenShift 4.6. Note that Tailor is now considered to be feature-complete and will only receive bug fixes going forward.
    25  Please have a look at the [changelog](https://github.com/opendevstack/tailor/blob/master/CHANGELOG.md) when upgrading.
    26  
    27  MacOS:
    28  
    29  ```
    30  curl -LO "https://github.com/opendevstack/tailor/releases/download/v1.3.4/tailor-darwin-amd64" && \
    31  chmod +x tailor-darwin-amd64 && mv tailor-darwin-amd64 /usr/local/bin/tailor
    32  ```
    33  
    34  Linux:
    35  
    36  ```
    37  curl -LO "https://github.com/opendevstack/tailor/releases/download/v1.3.4/tailor-linux-amd64" && \
    38  chmod +x tailor-linux-amd64 && mv tailor-linux-amd64 /usr/local/bin/tailor
    39  ```
    40  
    41  Windows (using Git Bash):
    42  
    43  ```
    44  curl -LO "https://github.com/opendevstack/tailor/releases/download/v1.3.4/tailor-windows-amd64.exe" && \
    45  chmod +x tailor-windows-amd64.exe && mv tailor-windows-amd64.exe /mingw64/bin/tailor.exe
    46  ```
    47  
    48  ## Usage
    49  
    50  There are three main commands: `diff`, `apply` and `export`. All commands depend on a current OpenShift session. To help with debugging (e.g. to see the `oc` commands which are executed in the background), use `--verbose`. More commands and options can be discovered via `tailor help`. All options can also be read from a file to ease usage, see section [Tailorfile](#tailorfile).
    51  
    52  ### `tailor diff / apply`
    53  `diff` compares the current state of a namespace with its desired state, and shows the resulting drift. The current state is determined by exporting the resources in the OpenShift cluster (via `oc get --export`). The desired state is computed by processing local OpenShift templates (via `oc process`), using any parameters given via the CLI or param files.
    54  
    55  `apply` does exactly the same as `diff`, but then asks whether to reconcile the drift, which can be done as a whole or on a per-resource basis.
    56  
    57  There are many options to control how the comparison is performed:
    58  
    59  * The namespace which is compared can be specificed via `--namespace|-n`. If not given, it defaults to the active namespace of the session.
    60  * Templates (`*.yml` files) are taken from `--template-dir|-t` (defaulting to the working dir).
    61  * Param files (`*.env` files) are taken from `--param-dir|-p` (defaulting to a directory with the same name as the target namespace in the current working dir; otherwise the working dir itself). Each param file is then used when processing the "corresponding" template (e.g. `foo.env` for template `foo.yml`).
    62  * Param files can also be referenced via `--param-file`. If a file named `<namespace>.env` exists in the working dir, it is automatically passed as `--param-file`.
    63  * Parameters can also be specified directly via `--param FOO=bar`.
    64  * If at least one of the processed templates does not consume all given parameters, `oc process` will fail to highlight this problem. To squelch this message, use `--ignore-unknown-parameters`.
    65  * By default, all resources in the namespace are compared, but you can adjust this by:
    66    * adding specific types as arguments to the command, e.g. `tailor diff pvc,dc`
    67    * passing `--selector/-l`, e.g. `-l app=foo` (multiple labels are comma-separated, and need to apply all)
    68    * specifying an individual resource, e.g. `dc/foo`
    69    * excluding resources via `--exclude|-e` (targeting types, resources or labels; e.g. `-e bc`, `-e dc/foo`, `-e app=foo`)
    70  * Sometimes there is state in the OpenShift cluster which is difficult to "know" in the templates. Tailor allows to keep the state of a field in OpenShift via `--preserve` (e.g. `--preserve bc`, `--preserve bc:foobar`, `--preserve bc:/spec/output/to/name`).
    71  * Changing the value of some fields (such as the `host` of a `Route`) is not allowed in OpenShift. Tailor detects if you do so and displays a warning that it would need to recreate the resource to apply the change. You may then permit this via `--allow-recreate` or avoid drift on such fields via `--preserve-immutable-fields`.
    72  * Drift on `Secret` resources is hidden by default for security reasons, and may be shown by passing `--reveal-secrets`.
    73  
    74  ### `tailor export`
    75  Export configuration of resources found in an OpenShift namespace to a cleaned
    76  YAML template, which is written to `STDOUT`. Tailor applies three optimisations to the result:
    77  
    78  - All fields controlled by the cluster are removed, such as `/metadata/creationTimestamp`.
    79  - Unless `--with-annotations` is given, some annotations (`kubectl.kubernetes.io/last-applied-configuration`, `openshift.io/image.dockerRepositoryCheck`) are removed. It is possible to remove further annotation(s) via `--trim-annotation`, either by exact match or by prefix match (e.g. `openshift.io/`).
    80  - Hardcoded occurences of the namespace are replaced with an automatically supplied parameter `TAILOR_NAMESPACE` so that the exported template can be used against multiple OpenShift projects (can be disabled by passing `--with-hardcoded-namespace`).
    81  
    82  
    83  ## How-To
    84  
    85  ### Template Authoring
    86  
    87  Please consult the [OpenShift Templates documentation](https://docs.openshift.com/container-platform/3.11/dev_guide/templates.html) on how to write templates to express the desired state. Tailor processes the templates using standard `oc process`, before the resulting resource list gets applied via `oc apply`. For in-depth knowledge about how the configuration in the templates gets applied to the current state in the cluster, read [Declarative Management of Kubernetes Objects Using Configuration Files](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/).
    88  
    89  Following is some guidance on how to author templates:
    90  
    91  * If the template specifies a parameter `TAILOR_NAMESPACE`, it is automatically filled based on the namespace against which Tailor is executed.
    92  * Some resource fields have useful server defaults (such as `.spec.host` of `Route` resources or `.spec.storageClassName` of `PersistentVolumeClaim` resources). It is possible to leave them out of the template, but Tailor will detect drift after the resource has been created (because the value is present in the live configuration, but absent in the template). One can use e.g. `--preserve route:/spec/host` to prevent this. Alternatively, some of those fields are also immutable, so using `--preserve-immutable-fields` can also work well.
    93  * Often it is easier to start authoring templates by exporting live configuration instead of starting from scratch. Also, sometimes it can be easier to apply a change in the UI and then figure out what needs to be updated in the template by running `tailor diff`.
    94  
    95  ### Working with Secrets
    96  
    97  Keeping the OpenShift configuration under version control necessitates to store secrets. To make it easy to do so in a safe fashion, Tailor comes with a `secrets` subcommand that allows to encrypt those secrets using PGP. The subcommands offers to `edit`, `re-encrypt` and `reveal` secrets, as well as adding new keypairs via `generate-key`.
    98  
    99  In general, secrets are just a special kind of params. Typically, params are located in `*.env` files, e.g. `FOO=bar`. Secrets an be kept in a `*.env.enc` file, where each line is e.g. `QUX=<encrypted content>`. When Tailor is processing templates, it merges `*.env` and `*.env.enc` files together. All params in `.env.enc` files are base64-encoded automatically by Tailor so that they can be used directly in OpenShift `Secret` resources. If you have a secret value that is a multiline string (such as a certificate), you can base64-encode it (e.g. `cat cert | base64`) and add the encoded string as a parameter into the `.env.enc` file like this: `FOO.B64=abc...`. The `.B64` suffix tells Tailor that the value is already in base64 encoding.
   100  
   101  In order to create and edit `*.env.enc` files, Tailor offers an `edit` command. `secrets edit foo.env.enc` opens a terminal editor, in which you can enter the params in plain, e.g. `PASSWORD=s3cr3t`. When saved, every param value will be encrypted for all public keys in `--public-key-dir="public-keys|."`. To read a file with encrypted params (e.g. to edit the secrets or compare the diff between desired and current state), you need your private key available at `--private-key="private.key"`.
   102  
   103  When a public key is added or removed, it is required to run `secrets re-encrypt`.
   104  This decrypts all params in `*.env.enc` files and writes them again using the provided public keys.
   105  
   106  The `secrets reveal foo.env.enc` command shows the param file after decrypting
   107  the param values so that you can see the clear text secrets.
   108  
   109  Finally, to ease PGP management, `secrets generate-key john.doe@domain.com` generates a PGP keypair, writing the public key to `john-doe.key` (which should be committed) and the private key to `private.key` (which MUST NOT be committed).
   110  
   111  
   112  ### Permissions
   113  
   114  Tailor needs access to a resource in order to be able to compare it. This means that to properly compare all resources, the user of the OpenShift session that Tailor makes use of needs to have enough rights. Failing, Tailor will error
   115  as it cannot compare some resources. To prevent this from happening, exclude the resource types (e.g. `rolebinding` and `serviceaccount`) that you do not have access to.
   116  
   117  
   118  ### Tailorfile
   119  
   120  Instead of passing flags ad-hoc to `tailor`, all options can be specified in a `Tailorfile`, which is a simple line-delimited file, e.g.:
   121  ```
   122  template-dir foo
   123  param-dir bar
   124  
   125  param FOO=bar
   126  param BAZ=qux
   127  
   128  bc,is,dc,svc
   129  ```
   130  Please note that boolean flags need to be specified with a value, e.g. `upsert-only true`.
   131  
   132  Tailor will automatically pick up any file named `Tailorfile.<namespace>` or `Tailorfile` in the working directory. Alternatively, a specific file can be selected via `tailor -f somefile`.
   133  
   134  ### Command Completion
   135  
   136  BASH/ZSH completion is available. Add this into `.bash_profile` or equivalent:
   137  ```
   138  eval "$(tailor --completion-script-$(echo $SHELL | awk -F/ '{print $NF}'))"
   139  ```
   140  
   141  ## Comparison to other tools
   142  
   143  ### Tailor vs. Helm
   144  * Compared to Helm v2, Tailor does not need a highly privileged Tiller. Helm v3 does not need it either.
   145  * Tailor works with plain OpenShift templates instead of Helm charts. OpenShift templates are simpler, and can easily be generated from existing resources in OpenShift.
   146  * Tailor has a narrower scope - it is basically an "`oc` on steroids". Helm has more extensive features like searching for charts etc.
   147  * Tailor targets OpenShift, Helm targets Kubernetes. Using Helm for OpenShift 3.11 has limitations / bugs around dealing with OpenShift resources such as `BuildConfig` or `Route`. Note those are fixed in [OpenShift 4.4](https://access.redhat.com/errata/RHBA-2020:0581).
   148  * Tailor allows to check for drift, and allows to review the difference between live configuration and desired state before applying.
   149  
   150  If you are a Tailor user wanting to migrate to Helm, check out the [migration guide](https://github.com/opendevstack/tailor/wiki/Migrating-from-Tailor-to-Helm).
   151  
   152  ### Tailor vs. kustomize
   153  * Tailor targets OpenShift, kustomize targets Kubernetes
   154  * Tailor uses a templating approach, kustomize uses patching
   155  * Tailor comes with its own drift/diff mechanism, whereas kustomize only focuses on specifying resources. However, newer versions of Kubernetes support `kubectl diff`, which can be used to view differences.
   156  
   157  ## FAQ / Troubleshooting
   158  
   159  ### Tailor does not recognize a certain resource kind
   160  
   161  Tailor currently supports `BuildConfig`, `CronJob`, `Job`, `Deployment`, `DeploymentConfig`, `ImageStream`, `LimitRange`, `PersistentVolumeClaim`, `ResourceQuota`, `RoleBinding`, `Route`, `Secret`, `Service`, `ServiceAccount`, `Template`, `HorizontalPodAutoscaler`, and `StatefulSet`. Some resources like `Build`, `Event`, `ImageStreamImage`, `ImageStreamTag`, `PersistentVolume`, `Pod`, `ReplicationController` are not supported by design as they are created and managed automatically by OpenShift. If you want to control a resource with Tailor that is not supported yet, but would be suitable, please [open an issue](https://github.com/opendevstack/tailor/issues/new).
   162  
   163  ### Why is it required to specify fields which have server defaults?
   164  
   165  When a field (such as `.spec.revisionHistoryLimit` of `DeploymentConfig` resources) is absent from a template, the server will default it when the template is applied. However, in subsequent runs, Tailor will detect drift for that field, suggesting to remove it (even though the path would not actually be removed as the server would default it again). Technically, it would be possible to prevent detecting drift for those circumstances (based on previously applied configuration), but it would run the risk that changes are made in the UI which would not be detected by Tailor, and therefore lead to situations where the live configuration does not match the desired state. Because of this, Tailor detects drift unless the field is also defined in the template, or the live value is preserved (via `--preserve ...`)
   166  
   167  ---
   168  
   169  ![](https://github.com/opendevstack/tailor/workflows/Continous%20Integration%20Tests/badge.svg?branch=master)
   170  
   171  
   172  
   173