github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/examples/variables/README.md (about)

     1  import Properties from '@site/src/components/SchemaItemProperties';
     2  import ExampleYAML from "@site/src/components/ExampleYAML";
     3  
     4  # Variables
     5  
     6  This example demonstrates how to define `variables` and `constants` in your package that will be templated across the manifests and charts your package uses during `jackal package deploy` with `###JACKAL_VAR_*###` and `###JACKAL_CONST_*###`, and also shows how package configuration templates can be used in the `jackal.yaml` during `jackal package create` with `###JACKAL_PKG_TMPL_*###`.
     7  
     8  With these variables and templating features, you can define values in the `jackal.yaml` file without having to set them manually in every manifest and chart, and can prompt the deploy user for certain information you may want to make dynamic on `jackal package deploy`.
     9  
    10  This becomes useful when you are working with an upstream chart that is often changing, or a lot of charts that have slightly different conventions for their values. Now you can standardize all of that from your `jackal.yaml` file.
    11  
    12  Text files are also templated during `jackal package deploy` so you can use these variables in any text file that you want to be templated.
    13  
    14  :::note
    15  
    16  Because files can be deployed without a Kubernetes cluster, some built-in variables such as `###JACKAL_REGISTRY###` may not be available if no previous component has required access to the cluster. If you need one of these built-in variables, a prior component will need to have been called that requires access to the cluster, such as `images`, `repos`, `manifests`, `dataInjections`.
    17  
    18  :::
    19  
    20  ## Deploy-Time Variables and Constants
    21  
    22  To use variables and constants at deploy time you need to have two things:
    23  
    24  1. a manifest that you want to template a value in
    25  2. a defined variable in the `jackal.yaml` file from `variables` or `setVariable`
    26  
    27  The manifest should have your desired variable name in ALL CAPS prefixed with `###JACKAL_VAR` for `variables` or prefixed with `###JACKAL_CONST` for `constants` and suffixed with `###`.  For example in a configmap that took a variable named `DATABASE_USERNAME` you would provide the following:
    28  
    29  ```yaml
    30  apiVersion: v1
    31  kind: ConfigMap
    32  metadata:
    33    name: db-configmap
    34  data:
    35    username: ###JACKAL_VAR_DATABASE_USERNAME###
    36  ```
    37  
    38  In the `jackal.yaml`, you would need to define the variable in the `variables` section or as output from an action with `setVariable` with the same `name` as above. Or for a constant you would use the `constants` section.  For the same example as above, you would have the following for a variable defined by the deploy user:
    39  
    40  ```yaml
    41  variables:
    42    name: DATABASE_USERNAME
    43    description: 'The username for the database'
    44  ```
    45  
    46  And the following for a variable defined as an output from an action:
    47  
    48  ```yaml
    49  components:
    50    - name: set-variable-example
    51      actions:
    52        onDeploy:
    53          after:
    54            - cmd: echo "username-value"
    55              setVariables:
    56                - name: DATABASE_USERNAME
    57  ```
    58  
    59  Jackal `variables` can also have additional fields that describe how Jackal will handle them which are described below:
    60  
    61  <Properties item="JackalPackageVariable" />
    62  
    63  :::info
    64  
    65  Variables with `type: file` will be set to the filepath in `actions` due to constraints on the size of environment variables in the shell.  This also allows for additional processing of the file by its filename.
    66  
    67  :::
    68  
    69  :::note
    70  
    71  The fields `default`, `description` and `prompt` are not available on `setVariables` since they always take the standard output of an action command and will not be interacted with directly by a deploy user.
    72  
    73  :::
    74  
    75  Jackal `constants` are similar but have fewer options as they are static by the time `jackal package deploy` is run:
    76  
    77  <Properties item="JackalPackageConstant" />
    78  
    79  :::note
    80  
    81  All names must match the regex pattern `^[A-Z0-9_]+$` [Test](https://regex101.com/r/BG5ZqW/1)).
    82  
    83  :::
    84  
    85  :::tip
    86  
    87  When not specifying `default`, `prompt`, `sensitive`, `autoIndent`, or `type` Jackal will default to `default: ""`, `prompt: false`, `sensitive: false`, `autoIndent: false`, and `type: "raw"`
    88  
    89  :::
    90  
    91  For user-specified variables, you can also specify a `default` value for the variable to take in case a user does not provide one on deploy, and can specify whether to `prompt` the user for the variable when not using the `--confirm` or `--set` flags.
    92  
    93  ```yaml
    94  variables:
    95    name: DATABASE_USERNAME
    96    default: 'postgres'
    97    prompt: true
    98  ```
    99  
   100  :::note
   101  
   102  Variables that do not have a default, are not `--set` and are not prompted for during deploy will be replaced with an empty string in manifests/charts/files
   103  
   104  :::
   105  
   106  For constants, you must specify the value they will use at package create. These values cannot be overridden with `--set` during `jackal package deploy`, but you can use package template variables (described below) to variablize them during `jackal package create`.
   107  
   108  ```yaml
   109  constants:
   110    name: DATABASE_TABLE
   111    value: 'users'
   112  ```
   113  
   114  :::note
   115  
   116  `jackal package create` only templates the `jackal.yaml` file, and `jackal package deploy` only templates other manifests, charts and files
   117  
   118  :::
   119  
   120  ## Create-Time Package Configuration Templates
   121  
   122  You can also specify package configuration templates at package create time by including `###_JACKAL_PKG_TMPL_*###` as the value for any string-type data in your package definition. These values are discovered during `jackal package create` and will always be prompted for if not using `--confirm` or `--set`. An example of this is below:
   123  
   124  ```yaml
   125  kind: JackalPackageConfig
   126  metadata:
   127    name: 'pkg-variables'
   128    description: 'Prompt for a variables during package create'
   129  
   130  constants:
   131    - name: PROMPT_IMAGE
   132      value: '###JACKAL_PKG_TMPL_PROMPT_ON_CREATE###'
   133  
   134  components:
   135    - name: jackal-prompt-image
   136      required: true
   137      images:
   138        - '###JACKAL_PKG_TMPL_PROMPT_ON_CREATE###'
   139  ```
   140  
   141  :::caution
   142  
   143  It is not recommended to use package configuration templates for any `sensitive` data as this will be baked into the package as plain text.  Please use a deploy-time variable with the `sensitive` key set instead.
   144  
   145  :::
   146  
   147  :::note
   148  
   149  You can only template string values in this way as non-string values will not marshal/unmarshal properly through the yaml.
   150  
   151  :::
   152  
   153  :::note
   154  
   155  If you use `--confirm` and do not `--set` all of the package configuration templates you will receive an error
   156  
   157  :::
   158  
   159  :::note
   160  
   161  You cannot template the component import path using package configuration templates
   162  
   163  :::
   164  
   165  ## `jackal.yaml` {#jackal.yaml}
   166  
   167  :::info
   168  
   169  To view the example in its entirety, select the `Edit this page` link below the article and select the parent folder.
   170  
   171  :::
   172  
   173  <ExampleYAML src={require('./jackal.yaml')} showLink={false} />