Setups

Functions of the tools module at v0.5.0. Each returns what a command runs in; import it with import * as tools from "tools".

aws.setup

What the AWS CLI and SDKs need from an environment: a profile, a region, an endpoint, credentials, and the directory profiles live in. Give it to another tool's --with — the Terraform AWS provider, an Ansible dynamic inventory — to run that tool with the same account.

aws.setup(
  --profile: String | Null = null,
  --region: String | Null = null,
  --endpoint_url: String | Null = null,
  --access_key_id: String | Null = null,
  --secret_access_key: String | Null = <secret>,
  --session_token: String | Null = <secret>,
  --config_dir: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Parameters

• --profile AWS_PROFILE: a profile from the config directory.
• --region AWS_REGION and AWS_DEFAULT_REGION; the CLI and the SDKs read different ones.
• --endpoint_url AWS_ENDPOINT_URL, for LocalStack or another AWS-compatible endpoint.
• --access_key_id AWS_ACCESS_KEY_ID.
• --secret_access_key!! AWS_SECRET_ACCESS_KEY; masked in the command log.
• --session_token!! AWS_SESSION_TOKEN; masked in the command log.
• --config_dir Host directory mounted read-only as /root/.aws, usually home(".aws").

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/aws.lask

gcloud.setup

What gcloud and the Google Cloud SDKs need from an environment: a project, a region, and credentials. Give it to another tool's --with — the Terraform Google provider, sops with Cloud KMS — to run that tool with the same account.

gcloud.setup(
  --project: String | Null = null,
  --region: String | Null = null,
  --credentials_file: String | Null = null,
  --access_token: String | Null = <secret>,
  --config_dir: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Parameters

• --project CLOUDSDK_CORE_PROJECT and GOOGLE_CLOUD_PROJECT; gcloud and the SDKs read different ones.
• --region CLOUDSDK_COMPUTE_REGION and GOOGLE_REGION.
• --credentials_file Host path of a service account key or an external account file, mounted read-only; GOOGLE_APPLICATION_CREDENTIALS for the SDKs and CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE for gcloud point at it.
• --access_token!! CLOUDSDK_AUTH_ACCESS_TOKEN and GOOGLE_OAUTH_ACCESS_TOKEN; masked in the command log.
• --config_dir Host directory mounted as /root/.config/gcloud, usually home(".config/gcloud"); read-write, since gcloud refreshes its tokens there.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/gcloud.lask

az.setup

What the Azure CLI and the Azure SDKs need from an environment: a subscription, a tenant, and a service principal. The variables are set under both names the tools read, ARM_* for the Terraform azurerm provider and AZURE_* for the SDKs, so the same setup serves either through --with.

az.setup(
  --subscription_id: String | Null = null,
  --tenant_id: String | Null = null,
  --client_id: String | Null = null,
  --client_secret: String | Null = <secret>,
  --config_dir: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Parameters

• --subscription_id ARM_SUBSCRIPTION_ID and AZURE_SUBSCRIPTION_ID.
• --tenant_id ARM_TENANT_ID and AZURE_TENANT_ID.
• --client_id ARM_CLIENT_ID and AZURE_CLIENT_ID: the service principal or managed identity.
• --client_secret!! ARM_CLIENT_SECRET and AZURE_CLIENT_SECRET; masked in the command log.
• --config_dir Host directory mounted as /root/.azure, usually home(".azure"); read-write, since az keeps its token cache there.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/az.lask

kube.setup

What a Kubernetes client needs from an environment: a kubeconfig, and the context and namespace to use from it. Give it to another tool's --with — the Terraform kubernetes and helm providers, Pulumi — to reach the same cluster.

kube.setup(
  --kubeconfig: String | Null = null,
  --context: String | Null = null,
  --namespace: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

The kubeconfig is mounted read-only, and the variables are set under each name the tools read: KUBECONFIG, KUBE_CONFIG_PATH (Terraform), HELM_KUBECONTEXT and KUBE_CTX, HELM_NAMESPACE. kubectl reads no variable for a context or a namespace: it uses the kubeconfig's current context unless --context and -n are given on its command line.

Parameters

• --kubeconfig Host path of the kubeconfig, e.g. home(".kube/config").
• --context The context Helm and Terraform use.
• --namespace The namespace Helm uses.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/kube.lask

psql.setup

What libpq and the clients built on it read to reach a PostgreSQL server: psql and pg_dump, psycopg, node-postgres, and most others. Give it to an application's environment through --with.

psql.setup(
  --host: String | Null = null,
  --port: String | Null = null,
  --user: String | Null = null,
  --password: String | Null = <secret>,
  --database: String | Null = null,
  --sslmode: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Parameters

• --host PGHOST.
• --port PGPORT.
• --user PGUSER.
• --password!! PGPASSWORD; masked in the command log.
• --database PGDATABASE.
• --sslmode PGSSLMODE, e.g. "require".

Returns Record<env: Map<String>, volumes: Array<String>>: The variables, for a tool's --with.

lib/psql.lask

vault.setup

What Vault clients read to reach a server: the vault CLI, the Terraform vault provider, most SDKs. Give it to another tool's --with.

vault.setup(
  --addr: String | Null = null,
  --token: String | Null = <secret>,
  --namespace: String | Null = null,
  --skip_verify: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Parameters

• --addr VAULT_ADDR.
• --token!! VAULT_TOKEN; masked in the command log.
• --namespace VAULT_NAMESPACE, for Vault Enterprise or HCP.
• --skip_verify VAULT_SKIP_VERIFY: "true" to accept a certificate the container cannot verify.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables, for a tool's --with.

lib/vault.lask

ssh.setup

An SSH identity: a key directory, an agent, or both.

ssh.setup(
  --dir: String | Null = null,
  --agent_socket: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

A key directory is mounted read-only at /root/.ssh. On a Linux host its files belong to the host's user, and ssh refuses a config file that neither root nor the running user owns; an agent socket has no such problem, and keeps the keys out of the container. With Docker Desktop the host's agent is at "/run/host-services/ssh-auth.sock"; on Linux it is the host's $SSH_AUTH_SOCK.

Parameters

• --dir Host directory mounted read-only at /root/.ssh, usually home(".ssh").
• --agent_socket Host path of an SSH agent socket, mounted at /run/ssh-agent.sock (SSH_AUTH_SOCK).

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/ssh.lask

git.setup

Git's identity and its access to private repositories over https.

git.setup(
  --token: String | Null = <secret>,
  --host: String = "github.com",
  --token_user: String = "x-access-token",
  --name: String | Null = null,
  --email: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

The configuration is carried in GIT_CONFIG_* variables, so nothing is written to a file: the mounted project is trusted (safe.directory), and with a token, https://<host>/ and git@<host>: are both rewritten to https with the token in the URL. That reaches every tool that clones through Git — go get of a private module, a git dependency of npm, Cargo or Bundler. The token is masked wherever it appears.

Parameters

• --token!! The access token; masked in the command log.
• --host The host the token is for.
• --token_user The user name the host expects beside a token: "x-access-token" for GitHub, "oauth2" for GitLab.
• --name GIT_AUTHOR_NAME and GIT_COMMITTER_NAME.
• --email GIT_AUTHOR_EMAIL and GIT_COMMITTER_EMAIL.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables, for a tool's --with.

lib/git.lask

docker.setup

The host's Docker daemon, for a tool that starts or inspects containers itself: an image scan of a local image, Testcontainers.

docker.setup(
  --socket: String = "/var/run/docker.sock"
): Record<env: Map<String>, volumes: Array<String>>

This hands the container the host's daemon, and with it root on the host: ask for it only where it is needed (lask spec 10.7).

Parameters

• --socket Host path of the daemon's socket.

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/docker.lask

registry.setup

Credentials for a container registry, for a tool that pulls from it itself: trivy, grype, syft.

registry.setup(
  --registry: String | Null = null,
  --username: String | Null = null,
  --password: String | Null = <secret>,
  --config_dir: String | Null = null
): Record<env: Map<String>, volumes: Array<String>>

Either a Docker configuration directory, mounted read-only (DOCKER_CONFIG), or a user name and password, set under the names each scanner reads. A configuration that keeps its credentials in a credential helper — Docker Desktop's "desktop" — holds none the container can use: pass the user name and password instead.

Parameters

• --registry The registry the user name and password are for, e.g. "ghcr.io".
• --username TRIVY_USERNAME, GRYPE_REGISTRY_AUTH_USERNAME and SYFT_REGISTRY_AUTH_USERNAME.
• --password!! TRIVY_PASSWORD, GRYPE_REGISTRY_AUTH_PASSWORD and SYFT_REGISTRY_AUTH_PASSWORD; masked in the command log.
• --config_dir Host directory mounted read-only at /run/docker (DOCKER_CONFIG), usually home(".docker").

Returns Record<env: Map<String>, volumes: Array<String>>: The variables and mounts, for a tool's --with.

lib/registry.lask