> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# timeedit/utility

Utility orb containing commands and jobs that are shared between projects.
Most parameters of string type have a default value which is "$VARIABLE".
The convention is to set the variable value in a env step because all commands and jobs sources $BASH_ENV, making those variables available then we can use the variables default values. Those parameters of type env_var_name are expected to just have the variable name excluding the "$", meaning "$VARIABLE" is incorrect but "VARIABLE" is correct.


## Commands

### docker_login

Does a docker login with defaults set to teartifacts in gcp Authenticates to teartifacts docker login.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `DOCKER_PASSWORD` | env_var_name | DOCKER_PASSWORD | The name of the variable containing the docker password for docker login authentication
 |
| `DOCKER_REGISTRY` | string | europe-docker.pkg.dev | Which registry to authenticate towards |
| `DOCKER_USERNAME` | string | _json_key_base64 | Used for docker login authentication |

### gcp_authenticate

Activates a service account to gcloud and sets gcp project ID and compute zone for subsequent commands.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_PROJECT_ID` | string | $GCP_PROJECT_ID | GCP project name |
| `GCP_SERVICE_KEY` | env_var_name | GCP_SERVICE_KEY | The name of the variable containing GCP_SERVICE_KEY, used for authentication with gcloud cli
 |

### gcp_lb_set_urlmap

Deploys an urlmap Uses env variable GCP_SERVICE_KEY, PROJECT_ID, URLMAP_SRC, and URLMAP_DST


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_PROJECT_ID` | string | $GCP_PROJECT_ID |  |
| `GCP_SERVICE_KEY` | env_var_name | GCP_SERVICE_KEY | The name of the variable containing GCP_SERVICE_KEY, used for authentication with gcloud cli
 |
| `GCP_URLMAP_DST` | string |  | The GCP urlmap that will be updated.
If the value is empty its defaulted to URL_MAP_SRC.
Value is always stripped of of its last file name extension.
 |
| `GCP_URLMAP_SRC` | string |  | A file path which contains a gcp urlmap
 |

### gcp_mig_clean_templates

Treats group of gcp instance templates that matches a pattern as a fifo queue and removes the oldest. Prerequisite: gcloud must be activated


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_MIG_TEMPLATE_QUEUE_SIZE` | integer | 30 | How many instance templates we will retain. The others will be discarded
 |
| `GCP_MIG_TEMPLATE_SIMPLE_PATTERN` | string | $GCP_TEMPLATE_SIMPLE_PATTERN | A simple pattern string. Anything that matches the pattern is
considered part of the fifo queue.
Can either be the pattern directly or a variable name which value is the pattern.
 |

### gcp_mig_set_instance_template

Set Managed instance group, MIG, instance template. Future vms will use this template, doesnt modify current running vm's


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_COMPUTE_ZONE` | string | $GCP_COMPUTE_ZONE | Which compute zone the GCP mig resides in
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_NAME` | string | $GCP_MIG_NAME | Name of the GCP managed instance group
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_TEMPLATE_NAME` | string | $GCP_MIG_TEMPLATE_NAME | Name of the GCP template to deploy to the instance group
Can either be the name directly or a variable name which value is the name.
 |

### gcp_mig_start_rolling_update

Start a managed instance group, MIG, rolling update


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_COMPUTE_ZONE` | string | $GCP_COMPUTE_ZONE | Which compute zone the GCP mig resides in
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_MAX_SURGE` | string | 50% | How many instances we can overshoot the max limit when performing an update
 |
| `GCP_MIG_MAX_UNAVAILABLE` | string | 50% | How many instances we can replace at a time when performing an update.
 |
| `GCP_MIG_NAME` | string | $GCP_MIG_NAME | Name of the GCP managed instance group
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_TEMPLATE_NAME` | string | $GCP_MIG_TEMPLATE_NAME | Name of the GCP template to deploy to the instance group
Can either be the name directly or a variable name which value is the name.
 |

### gcp_mig_wait_until_stable

Wait for Managed instance group, MIG, to stabilize after starting rolling update


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_COMPUTE_ZONE` | string | $GCP_COMPUTE_ZONE | Which compute zone the GCP mig resides in
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_NAME` | string | $GCP_MIG_NAME | Name of the GCP managed instance group
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_MIG_TIMEOUT_S` | integer | 1800 | How long to wait in seconds before exiting with error |

### gcp_run_remove_revision_tag

Removes cloud run tag or tags


| Parameter | Type | Default | Description |
|---|---|---|---|
| `CIRCLECI_WHEN` | string | always | A circleci when attribute changes when the step is executed. |
| `GCP_RUN_REGION` | string | $GCP_RUN_REGION | The region name the cloud run service operates in.
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_RUN_REVISION_TAG` | string |  | The name of the tag to be associated with the cloud run revision
 |
| `GCP_RUN_SERVICE_NAME` | string | $GCP_RUN_SERVICE_NAME | Name of the cloud run service in GCP.
Can either be the name directly or a variable name which value is the name.
 |

### gcp_run_tag_revision

Tags a cloud run revision


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_RUN_REGION` | string | $GCP_RUN_REGION | The region name the cloud run service operates in.
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_RUN_REVISION_SUFFIX` | string |  | The string to identify a revision of the cloud run service
 |
| `GCP_RUN_REVISION_TAG` | string |  | The name of the tag to be associated with the cloud run revision
 |
| `GCP_RUN_SERVICE_NAME` | string | $GCP_RUN_SERVICE_NAME | Name of the cloud run service in GCP.
Can either be the name directly or a variable name which value is the name.
 |

### gcp_run_update_traffic_to_tag

Send traffic to tagged revision


| Parameter | Type | Default | Description |
|---|---|---|---|
| `GCP_RUN_REGION` | string | $GCP_RUN_REGION | The region name the cloud run service operates in.
Can either be the name directly or a variable name which value is the name.
 |
| `GCP_RUN_REVISION_TAG` | string |  | The name of the tag to be associated with the cloud run revision
 |
| `GCP_RUN_SERVICE_NAME` | string | $GCP_RUN_SERVICE_NAME | Name of the cloud run service in GCP.
Can either be the name directly or a variable name which value is the name.
 |

### tesafe_get_secrets

Creates the script /tmp/get_secret and /tmp/get_secret_esc.
Both scripts creates /tmp/TE_SAFE_TOKEN from TE_SAFE_TOKEN env.
When executing command uses TE_SAFE_CONTEXT as env and secret name as argument.
Example: "TE_SAFE_TOKEN=<token> TE_SAFE_CONTEXT=<context> /tmp/get_secret_escape <secret_name>"
Circleci example:
  export TE_SAFE_TOKEN=<token>
  export TE_SAFE_CONTEXT=<context>
  cat << EOF > $BASH_ENV
  export my_value=$(/tmp/get_secret_esc /secret_name)
  EOF

/tmp/get_secret_scp Generates a secret that is shell escaped suitable for shell injection.


## Jobs

### docker_build_and_publish

Build and publish docker image


| Parameter | Type | Default | Description |
|---|---|---|---|
| `DOCKER_PASSWORD` | env_var_name | DOCKER_PASSWORD | Defaults to variable $DOCKER_PASSWORD. If its gcp service account key
it must be base64 encoded
 |
| `DOCKER_REGISTRY` | string | europe-docker.pkg.dev |  |
| `DOCKER_USERNAME` | string | _json_key_base64 |  |
| `EXECUTOR_IMAGE` | string | cimg/base:2023.01-22.04 | Sets the executor image |
| `EXECUTOR_RESOURCE_CLASS` | string | small |  |
| `STEPS_BUILD_PUBLISH_DOCKER` | steps |  | Build and publish docker command
Example: docker buildx build...
 |
| `STEPS_ENVIRONMENT` | steps |  | A step exporting variables to BASH_ENV. Also add any code here to setup the build like pulling submodules.
 |

### gcp_mig_clean_templates

Treats group of gcp instance templates that matches a pattern as a fifo queue and removes the oldest


| Parameter | Type | Default | Description |
|---|---|---|---|
| `EXECUTOR_IMAGE` | string | google/cloud-sdk:alpine | Sets the executor image |
| `EXECUTOR_RESOURCE_CLASS` | string | small |  |
| `GCP_MIG_TEMPLATE_QUEUE_SIZE` | integer | 30 |  |
| `GCP_MIG_TEMPLATE_SIMPLE_PATTERN` | string | $GCP_TEMPLATE_SIMPLE_PATTERN |  |
| `GCP_PROJECT_ID` | string | $GCP_PROJECT_ID | GCP project name |
| `GCP_SERVICE_KEY` | env_var_name | GCP_SERVICE_KEY | The contents of GCP service account key file |
| `STEPS_ENVIRONMENT` | steps |  |  |

### gcp_mig_deploy_new_template

Deploy instance template to MIG


| Parameter | Type | Default | Description |
|---|---|---|---|
| `EXECUTOR_IMAGE` | string | google/cloud-sdk:alpine | Sets the executor image |
| `EXECUTOR_RESOURCE_CLASS` | string | small |  |
| `GCP_COMPUTE_ZONE` | string | $GCP_COMPUTE_ZONE | GCP compute zone name |
| `GCP_MIG_MAX_SURGE` | string | 50% | How many extra nodes we can overshoot our limits with when replacing the active |
| `GCP_MIG_MAX_UNAVAILABLE` | string | 50% | How many nodes we can offline and replace among the active |
| `GCP_MIG_NAME` | string | $GCP_MIG_NAME | Name of the GCP managed instance group |
| `GCP_MIG_TEMPLATE_NAME` | string | $GCP_MIG_TEMPLATE_NAME | Name of the GCP template to deploy to the instance group |
| `GCP_MIG_TIMEOUT_S` | integer | 1800 | How long to wait in seconds before exiting with error. |
| `GCP_PROJECT_ID` | string | $GCP_PROJECT_ID | GCP project name |
| `GCP_SERVICE_KEY` | env_var_name | GCP_SERVICE_KEY | The contents of GCP service account key file |
| `GCP_URLMAP_DST` | string |  | Name of the urlmap in gcp that will be overwritten with new data.
If no argument is provided it will default to the value of GCP_URLMAP_SRC.
The value is always stripped to a basename without file_extension
e.g. .urlmaps/prod-lb.yml becomes prod-lb
 |
| `GCP_URLMAP_SRC` | string |  | A path to a file which contains an urlmap export.
Convention should be .urlmaps/*.yml.
When value is empty the step provisioning step will be skipped
 |
| `STEPS_ENVIRONMENT` | steps |  | Should generate the file $BASH_ENV which other steps will source to get variables
 |
| `STEPS_MIG_CREATE_TEMPLATE` | steps |  | The command to create an instance template in GCP.
Start of an example;
gcloud compute instance-templates create-with-container $INSTANCE_TEMPLATE_NAME
 |

### gcp_run_deploy

Deploy instance template to Cloud Run.
A tag is expected if you want
to use the other cloud run jobs in this orb.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `EXECUTOR_IMAGE` | string | google/cloud-sdk:alpine | Sets the executor image |
| `EXECUTOR_RESOURCE_CLASS` | string | small |  |
| `GCP_PROJECT_ID` | string | $GCP_PROJECT_ID | GCP project name |
| `GCP_RUN_REGION` | string | $GCP_RUN_REGION | The region name the cloud run service operates in.
Can either be the region directly or a variable name which value is the region.
 |
| `GCP_RUN_REVISION_SUFFIX` | string | $GCP_RUN_REVISION_SUFFIX | The suffix string to the cloud run revision
 |
| `GCP_RUN_REVISION_TAG` | string | $GCP_RUN_REVISION_TAG | The tag string to the cloud run revision
 |
| `GCP_RUN_SERVICE_NAME` | string | $GCP_RUN_SERVICE_NAME | Name of the cloud run service
 |
| `GCP_SERVICE_KEY` | env_var_name | GCP_SERVICE_KEY | The contents of GCP service account key file |
| `STEPS_ENVIRONMENT` | steps |  | Should generate the file $BASH_ENV which
other steps will source to get variables
 |
| `STEPS_GCP_RUN_CREATE_REVISION` | steps |  | Create a new cloud run revision, candidate, with a tag but no traffic
 |
| `STEPS_GCP_RUN_TEST_ON_TAG` | steps |  | Test towards the tagged revision.
If tests exit code is 0, then the tagged revision will be activated.
If the test fails, then the tag will be removed and we keep serving
traffic from current
 |

## Examples

### example

Sample example description.


```yaml
version: '2.1'
orbs:
  <orb-name>: <namespace>/<orb-name>@1.2.3
workflows:
  use-my-orb:
    jobs:
      - <orb-name>/<job-name>
```