diff --git a/website/content/partials/tools/nomad-pack/options-approval.mdx b/website/content/partials/tools/nomad-pack/options-approval.mdx new file mode 100644 index 000000000..2654bbfd8 --- /dev/null +++ b/website/content/partials/tools/nomad-pack/options-approval.mdx @@ -0,0 +1,4 @@ +### Approval options + +- `-auto-approve`: Automatically answer confirmation prompts in the + affirmative. diff --git a/website/content/partials/tools/nomad-pack/options-nomad-cluster.mdx b/website/content/partials/tools/nomad-pack/options-nomad-cluster.mdx new file mode 100644 index 000000000..f6e94cbef --- /dev/null +++ b/website/content/partials/tools/nomad-pack/options-nomad-cluster.mdx @@ -0,0 +1,25 @@ +### Nomad cluster options + +- `-address=`: The address of the Nomad server. Overrides the NOMAD_ADDR + environment variable if set. +- `-namespace=`: The target namespace for queries and actions bound to a + namespace. Overrides the NOMAD_NAMESPACE environment variable if set. +- `-region=`: The region of the Nomad servers to forward commands to. + Overrides the NOMAD_REGION environment variable if set. +- `-ca-cert=`: Path to a PEM encoded CA cert file to use to verify the + Nomad server SSL certificate. Overrides the NOMAD_CACERT environment variable + if set. +- `-client-cert=`: Path to a PEM encoded client certificate for TLS + authentication to the Nomad server. Must also specify `--client-key`. + Overrides the NOMAD_CLIENT_CERT environment variable if set. +- `-client-key=`: Path to an unencrypted PEM encoded private key + matching the client certificate from `--client-cert`. Overrides the + NOMAD_CLIENT_KEY environment variable if set. +- `-tls-server-name=`: The server name to use as the SNI host when + connecting via TLS. Overrides the NOMAD_TLS_SERVER_NAME environment variable + if set. +- `-token=`: The SecretID of an ACL token to use to authenticate API + requests with. Overrides the NOMAD_TOKEN environment variable if set. +- `-tls-skip-verify`: Do not verify TLS certificate. We do not recommend this. + Verification is also skipped if you set the NOMAD_SKIP_VERIFY environment + variable. diff --git a/website/content/partials/tools/nomad-pack/options-operations.mdx b/website/content/partials/tools/nomad-pack/options-operations.mdx new file mode 100644 index 000000000..0e51d2fca --- /dev/null +++ b/website/content/partials/tools/nomad-pack/options-operations.mdx @@ -0,0 +1,24 @@ +### Operation options + +- `-var-file=`: Specifies the path to a variable override file. You may + provide this multiple times on a single command for multiple files. +- `-allow-unset-vars`: Suppress errors from unset variables without default + values. Equivalent of setting the NOMAD_PACK_ALLOW_UNSET_VARS environment + variable to `1` or `true`. +- `-ignore-missing-vars`: Determines whether the command should override + variables not present in the pack or should produce an error. +- `-var=`: Specifies single override variables in the form of HCL + syntax. You may specify multiple times per command. +- `-name=`: If set, this is the unique identifier of this deployed + instance of the specified pack. If not set, the pack name becomes the unique + identifier. Setting a name is useful for running more than one instance of a + pack within the same cluster. Note that this name must be globally unique + within a cluster. Running the run command multiple times with the same name + re-submits the same pack and applies changes if you have made any to the + underlying pack. Be mindful that, whether you have made changes or not, the + underlying allocations are replaced.When managing packs, the name specified + here is the name that you should be pass to Nomad Packs' `plan` and `destroy` + commands. +- `-parser-v1`: Use the legacy syntax parser to parse your job. This enables + pack to run packs for earlier versions while you are migrating them to the + new syntax diff --git a/website/content/tools/nomad-pack/commands/deps/index.mdx b/website/content/tools/nomad-pack/commands/deps/index.mdx new file mode 100644 index 000000000..e28b9fbf7 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/deps/index.mdx @@ -0,0 +1,16 @@ +--- +layout: commands +page_title: nomad-pack deps command reference +description: |- + Use the `nomad-pack deps` command to manage dependencies for a Nomad pack. +--- + +# nomad-pack deps command reference + +Use the `nomad-pack deps` command to manage dependencies for a Nomad pack. + +## Usage + +```plaintext +nomad-pack deps [options] +``` diff --git a/website/content/tools/nomad-pack/commands/deps/vendor.mdx b/website/content/tools/nomad-pack/commands/deps/vendor.mdx new file mode 100644 index 000000000..71183ed21 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/deps/vendor.mdx @@ -0,0 +1,34 @@ +--- +layout: commands +page_title: nomad-pack deps vendor command reference +description: |- + Use the `nomad-pack deps vendor` command to download vendor dependencies for a pack. +--- + +# nomad-pack deps vendor command reference + +Use the `nomad-pack deps vendor` command to download vendor dependencies for a pack. + +## Usage + +```plaintext +nomad-pack deps vendor [options] +``` + +## Options + +- `--path=`: Full path to the pack that contains vendor dependencies. + All the dependencies are then downloaded into a `deps/` subdirectory of that + path. + +- `--timeout= (default 30)`: Timeout in seconds for downloading + dependencies. Defaults to 30. + +## Examples + +Download vendor dependencies for a pack in the current directory, with a timeout +of 180 seconds. + +```shell +nomad-pack deps vendor --timeout=180 +``` diff --git a/website/content/tools/nomad-pack/commands/destroy.mdx b/website/content/tools/nomad-pack/commands/destroy.mdx new file mode 100644 index 000000000..c968d36e5 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/destroy.mdx @@ -0,0 +1,53 @@ +--- +layout: commands +page_title: nomad-pack destroy command reference +description: |- + Use the `nomad-pack destroy` command to stop and delete the specified Nomad pack from the configured Nomad cluster. +--- + +# nomad-pack destroy command reference + +Use the `nomad-pack destroy` command to stop and delete the specified Nomad pack +from the configured Nomad cluster. This is the same as using the command +`nomad-pack stop --purge`. + +By default, the `nomad-pack destroy` command deletes all jobs in the pack +deployment. If you ran a pack with var overrides to specify the job name, you +must provide the var override when destroying the pack to guarantee this command +targets the correct job in the pack deployment. + +## Usage + +```plaintext +nomad-pack destroy [options] +``` + +## Options + +- `-registry=`: Specific registry name containing the pack to be + destroyed. +- `-ref=`: Specific Git reference of the pack to destroy. + Supports tags, SHA, and latest. If no ref is specified, + defaults to latest. Using `ref` with a file path is not supported. +- `-global`: Destroy multi-region pack in all its regions. By default, + `destroy` only destroys a single region at a time. Ignored for single-region packs. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +## Examples + +Stop an example pack in deployment "dev" and delete it from the cluster. + +```shell +nomad-pack destroy example --name=dev +``` + +Stop and delete an example pack in deployment "dev" that has a job named "test". +If you have installed the same pack in deployment "dev" but override the job +name to "hello", this command only destroys "test". + +```shell +nomad-pack destroy example --name=dev --var=job_name=test +``` diff --git a/website/content/tools/nomad-pack/commands/generate/index.mdx b/website/content/tools/nomad-pack/commands/generate/index.mdx new file mode 100644 index 000000000..01fd297ff --- /dev/null +++ b/website/content/tools/nomad-pack/commands/generate/index.mdx @@ -0,0 +1,16 @@ +--- +layout: commands +page_title: nomad-pack generate command reference +description: |- + Use the `nomad-pack generate` subcommands to generate a sample registry, pack, or variable overrides file for a Nomad pack. +--- + +# nomad-pack generate command reference + +Use the `nomad-pack generate` subcommands to generate a sample registry, pack, or variable overrides file for a Nomad pack. + +## Usage + +```plaintext +nomad-pack generate [options] +``` diff --git a/website/content/tools/nomad-pack/commands/generate/pack.mdx b/website/content/tools/nomad-pack/commands/generate/pack.mdx new file mode 100644 index 000000000..cc9d11e8d --- /dev/null +++ b/website/content/tools/nomad-pack/commands/generate/pack.mdx @@ -0,0 +1,31 @@ +--- +layout: commands +page_title: nomad-pack generate pack command reference +description: |- + Use the `nomad-pack generate pack` command to create a new Nomad pack. +--- + +# nomad-pack generate pack command reference + +Use the `nomad-pack generate pack` command to create a new Nomad pack. + +## Usage + +```plaintext +nomad-pack generate pack +``` + +## Options + +- `-to-dir=`: Path to write generated pack to. +- `-overwrite`: If the output directory is not empty, should we overwrite? + +@include 'tools/nomad-pack/options-approval.mdx' + +## Examples + +Create a new pack named "my-new-pack" in the current directory. + +```shell +nomad-pack generate pack my-new-pack +``` diff --git a/website/content/tools/nomad-pack/commands/generate/registry.mdx b/website/content/tools/nomad-pack/commands/generate/registry.mdx new file mode 100644 index 000000000..1ac19c85e --- /dev/null +++ b/website/content/tools/nomad-pack/commands/generate/registry.mdx @@ -0,0 +1,31 @@ +--- +layout: commands +page_title: nomad-pack generate registry command reference +description: |- + Use the `nomad-pack generate registry` command to generate a new registry. +--- + +# nomad-pack generate registry command reference + +Use the `nomad-pack generate registry` command to generate a new registry. + +## Usage + +```plaintext +nomad-pack generate registry +``` + +## Options + +- `-to-dir=`: Path to write generated registry to. +- `-with-sample-pack`: Generate a sample "hello_world" pack in the registry. + +@include 'tools/nomad-pack/options-approval.mdx' + +## Examples + +Create a new registry named "my-new-registry" in the current directory. + +```shell +nomad-pack generate registry my-new-registry +``` diff --git a/website/content/tools/nomad-pack/commands/generate/var-file.mdx b/website/content/tools/nomad-pack/commands/generate/var-file.mdx new file mode 100644 index 000000000..600e24c95 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/generate/var-file.mdx @@ -0,0 +1,63 @@ +--- +layout: commands +page_title: nomad-pack generate var-file command reference +description: |- + Use the `nomad-pack generate registry` command to generate a variable override file for a pack. +--- + +# nomad-pack generate var-file command reference + +Use the `nomad-pack generate registry` command to generate a variable override file for a pack. + +## Usage + +```plaintext +nomad-pack generate var-file [options] +``` + +## Options + +- `-registry=`: Specific registry name containing the target pack. If + not specified, the default registry is used. +- `-ref=`: Specific Git reference of the target pack. Supports tags, + SHA, and `@latest`. If you do not specify a reference, the command defaults to + `@latest`. Using `ref` with a file path is not supported. +- `-to-file=`: Path to write generated variable override file to in + addition to standard output. + +@include 'tools/nomad-pack/options-approval.mdx' + +## Examples + +Generate a variables override file for the given pack to standard output. + +```shell +nomad-pack generate var-file example +``` + +Generate a variable override for the example pack. Output to a file in +addition to the terminal. + +```shell +nomad-pack generate var-file example --to-file ./overrides.hcl +``` + +Generate a variable override for the `example` pack. Output to a file in +addition to the terminal. Setting the `auto-approve` option allows the command +to overwrite existing files. + +```shell +nomad-pack generate var-file example --to-file ./overrides.hcl --auto-approve +``` + +Generate a variable override pack under development from the current working directory. + +```shell +nomad-pack generate var-file . +``` + +Generate a variable override pack under development from the specified relative path. + +```shell +nomad-pack generate var-file ../../my-pack +``` diff --git a/website/content/tools/nomad-pack/commands/index.mdx b/website/content/tools/nomad-pack/commands/index.mdx new file mode 100644 index 000000000..7c3641b0b --- /dev/null +++ b/website/content/tools/nomad-pack/commands/index.mdx @@ -0,0 +1,14 @@ +--- +layout: docs +page_title: Nomad Pack command-line interface (CLI) reference +description: > + The Nomad Pack command-line interface (CLI) interacts with the Nomad Pack product. This section contains reference information on how to use the Nomad Pack CLI to generate, register, and list packs. +--- + +# Nomad Pack command-line interface (CLI) reference + +The Nomad Pack CLI is a well-behaved command-line application. In erroneous +cases, the CLI returns a non-zero exit status. To view a list of available +commands, run the `nomad-pack` command with no arguments, `-h`, or `--help`. To +access help for any specific subcommand, run the subcommand with the `-h` +argument. diff --git a/website/content/tools/nomad-pack/commands/info.mdx b/website/content/tools/nomad-pack/commands/info.mdx new file mode 100644 index 000000000..9acb34601 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/info.mdx @@ -0,0 +1,34 @@ +--- +layout: commands +page_title: nomad-pack info command reference +description: |- + Use the `nomad-pack info` command to fetch information on the given pack including name, description, and variable details. +--- + +# nomad-pack info command reference + +Use the `nomad-pack info` command to fetch information on the given pack including name, description, and variable details. + +## Usage + +```plaintext +nomad-pack info +``` + +## Options + +- `-registry=`: Specific registry name containing the pack to retrieve + info about. If not specified, this command targets the default registry. +- `-ref=`: Specific Git reference of the pack to retrieve info + about. Supports tags, SHA, and `@latest`. If you do not specify a reference, + the value defaults to `@latest`. Using `ref` with a file path is not supported. + +@include 'tools/nomad-pack/options-operations.mdx' + +## Examples + +Fetch information on the "hello_world" pack. + +```shell +nomad-pack info hello_world +``` diff --git a/website/content/tools/nomad-pack/commands/list.mdx b/website/content/tools/nomad-pack/commands/list.mdx new file mode 100644 index 000000000..4da1f386f --- /dev/null +++ b/website/content/tools/nomad-pack/commands/list.mdx @@ -0,0 +1,33 @@ +--- +layout: commands +page_title: nomad-pack list command reference +description: |- + Use the `nomad-pack list` command to list packs available in the local environment. +--- + +# nomad-pack list command reference + +Use the `nomad-pack list` command to list packs available in the local environment. + +## Usage + +```plaintext +nomad-pack list +``` + +## Options + +- `-registry=`: Registry name to filter packs by. +- `-ref=`: Registry ref to filter packs by. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +## Examples + +List all available packs. + +```shell +nomad-pack list +``` diff --git a/website/content/tools/nomad-pack/commands/plan.mdx b/website/content/tools/nomad-pack/commands/plan.mdx new file mode 100644 index 000000000..8b748739d --- /dev/null +++ b/website/content/tools/nomad-pack/commands/plan.mdx @@ -0,0 +1,75 @@ +--- +layout: commands +page_title: nomad-pack plan command reference +description: |- + Use the `nomad-pack plan` command to perform a dry run that determines the effects of submitting a new or updated Nomad Pack. +--- + +# nomad-pack plan command reference + +Use the `nomad-pack plan` command to perform a dry run that determines the effects of submitting a new or updated Nomad Pack. + +The `nomad-pack plan` command returns one of the following exit codes: + + - `0`: No objects will be created or destroyed. + - `1`: Objects will be created or destroyed. + - `255`: An error occurred determining the plan. + +## Usage + +```plaintext +nomad-pack plan [options] +``` + +## Options + +- `-registry=`: Specific registry name containing the pack. +- `-ref=`: Specific Git reference of the pack to retrieve info about. + Supports tags, SHA, and `@latest`. If you do not specify a reference, the + value defaults to `@latest`. Using `ref` with a file path is not supported. +- `-diff`: Determines whether to output the diff between the remote job and + planned job. Defaults to true. +- `-policy-override`: Sets the flag to force override any soft mandatory + Sentinel policies. +- `-verbose`: Increase diff verbosity. +- `-exit-code-no-changes=`: Override exit code returned when the plan shown + no changes. +- `-exit-code-makes-changes=`: Override exit code returned when the plan + shows changes. +- `-exit-code-error=`: Override exit code returned when there is an error. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +## Examples + +Plan an example pack with the default deployment name. + +```shell +nomad-pack plan example +``` + +Plan an example pack at a specific ref. + +```shell +nomad-pack plan example --ref=v0.0.1 +``` + +Plan a pack from a registry other than the default registry. + +```shell +nomad-pack plan traefik --registry=community --ref=v0.0.1 +``` + +Plan an example pack without showing the diff. + +```shell +nomad-pack plan example --diff=false +``` + +Plan a pack under development from the current filesystem. + +```shell +nomad-pack plan . +``` diff --git a/website/content/tools/nomad-pack/commands/registry/add.mdx b/website/content/tools/nomad-pack/commands/registry/add.mdx new file mode 100644 index 000000000..a460fa772 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/registry/add.mdx @@ -0,0 +1,51 @@ +--- +layout: commands +page_title: nomad-pack registry add command reference +description: |- + Use the `nomad-pack registry add` command to add registries or packs to the local environment. +--- + +# nomad-pack registry add command reference + +Use the `nomad-pack registry add` command to add registries or packs to the local environment. + +## Usage + +```plaintext +nomad-pack registry add [options] +``` + +## Options + +- `-target=`: A specific pack within the registry. +- `-ref=`: Specific Git reference of the registry or pack. Supports +tags, SHA, and `latest`. If you do not specify a reference, the command defaults +to `@latest`. Running `nomad registry add` multiple times for the same ref is +idempotent. However, running`nomad-pack registry add` without specifying a +reference or when specifying `@latest` is destructive and overwrites current +`@latest` in the global cache. Using `ref` with a file path is not supported. + +## Examples + +Download latest reference of the Nomad Pack registry to the global cache. + +```shell +nomad-pack registry add community \ + github.com/hashicorp/nomad-pack-community-registry +``` + +Download latest reference of a specific pack from the registry to the global cache. + +```shell +nomad-pack registry add community \ + github.com/hashicorp/nomad-pack-community-registry \ + --target=nomad_example +``` + +Download packs from a registry at a specific tag, release, or SHA. + +```shell +nomad-pack registry add community \ + github.com/hashicorp/nomad-pack-community-registry \ + --ref=v0.1.0 +``` diff --git a/website/content/tools/nomad-pack/commands/registry/delete.mdx b/website/content/tools/nomad-pack/commands/registry/delete.mdx new file mode 100644 index 000000000..f5458f1f6 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/registry/delete.mdx @@ -0,0 +1,44 @@ +--- +layout: commands +page_title: nomad-pack registry delete command reference +description: |- + Use the `nomad-pack registry delete` command to delete registries or packs from the local environment. +--- + +# nomad-pack registry delete command reference + +Use the `nomad-pack registry delete` command to delete registries or packs from the local environment. + +## Usage + +```plaintext +nomad-pack registry delete [options] +``` + +## Options + +- `-target=`: A specific pack within the registry. If you add a + reference flag, the command only deletes that reference of the target pack. +- `-ref=`: Specific Git reference of the registry or pack. Supports + tags, SHA, and `@latest`. If you do not specify a reference, the command defaults to `@latest`. Using `ref` with a file path is not supported. + + + +If you do not specify `target` or `ref`, this command deletes the entire +specified registry. + + + +## Examples + +Delete the Traefik pack with tag `v0.0.1` from your local `community` registry. + +```shell +nomad-pack registry delete community --target=traefik --ref=v0.0.1 +``` + +Delete the `community` registry from the local environment. + +```shell +nomad-pack registry delete community +``` diff --git a/website/content/tools/nomad-pack/commands/registry/index.mdx b/website/content/tools/nomad-pack/commands/registry/index.mdx new file mode 100644 index 000000000..1ddc10e23 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/registry/index.mdx @@ -0,0 +1,16 @@ +--- +layout: commands +page_title: nomad-pack registry command reference +description: |- + Use the ` nomad-pack registry` subcommands to add, delete, or list registries and packs in the local environment. +--- + +# nomad-pack registry command reference + +Use the `nomad-pack registry` subcommands to add, delete, or list registries and packs in the local environment. + +## Usage + +```plaintext +nomad-pack registry [options] +``` diff --git a/website/content/tools/nomad-pack/commands/registry/list.mdx b/website/content/tools/nomad-pack/commands/registry/list.mdx new file mode 100644 index 000000000..416566f7b --- /dev/null +++ b/website/content/tools/nomad-pack/commands/registry/list.mdx @@ -0,0 +1,16 @@ +--- +layout: commands +page_title: nomad-pack registry list command reference +description: |- + Use the `nomad-pack registry list` command to list registries configured in the local environment. +--- + +# nomad-pack registry list command reference + +Use the `nomad-pack registry list` command to list registries configured in the local environment. + +## Usage + +```plaintext +nomad-pack registry list +``` diff --git a/website/content/tools/nomad-pack/commands/render.mdx b/website/content/tools/nomad-pack/commands/render.mdx new file mode 100644 index 000000000..3333892df --- /dev/null +++ b/website/content/tools/nomad-pack/commands/render.mdx @@ -0,0 +1,71 @@ +--- +layout: commands +page_title: nomad-pack render command reference +description: |- + Use the `nomad-pack render` command to render the specified Nomad Pack and review the results. +--- + +# nomad-pack render command reference + +Use the `nomad-pack render` command to render the specified Nomad Pack and review the results. + +## Usage + +```plaintext +nomad-pack render [options] +``` + +## Options + +- `-registry=`: Specific registry name containing the pack. If not + specified, the default registry is used. +- `-ref=`: Specific Git reference of the pack to retrieve info about. + Supports tags, SHA, and `@latest`. If you do not specify a reference, the + value defaults to `@latest`. Using `ref` with a file path is not supported. +- `-render-output-template`: Controls whether or not to render and display the + output template file within the pack. +- `-skip-aux-files`: Controls whether or not the rendered output contains + auxiliary files found in the `templates` folder. +- `-no-format`: Controls whether or not to format templates before outputting. +- `-to-dir=`: Path to write rendered job files to in addition to + standard output. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-approval.mdx' + +## Examples + +Render an example pack with override variables in a variable file. + +```shell +nomad-pack render example --var-file="./overrides.hcl" +``` + +Render an example pack with CLI variable overrides. + +```shell +nomad-pack render example --var="redis_image_version=latest" \ + --var="redis_resources={"cpu": "1000", "memory": "512"}" +``` + +Render an example pack including the outputs template file. + +```shell +nomad-pack render example --render-output-template +``` + +Render an example pack, outputting the rendered templates to file in +addition to the terminal. Setting `auto-approve` allows the command to +overwrite existing files. + +```shell +nomad-pack render example --to-dir ~/out --auto-approve +``` + +Render a pack under development from the filesystem. Supports current +working directory or relative path. + +```shell +nomad-pack render . +``` diff --git a/website/content/tools/nomad-pack/commands/run.mdx b/website/content/tools/nomad-pack/commands/run.mdx new file mode 100644 index 000000000..b9bfcb33d --- /dev/null +++ b/website/content/tools/nomad-pack/commands/run.mdx @@ -0,0 +1,85 @@ +--- +layout: commands +page_title: nomad-pack run command reference +description: |- + Use the `nomad-pack run` command to install the specified Nomad Pack to a configured Nomad cluster. +--- + +# nomad-pack run command reference + +Use the `nomad-pack run` command to install the specified Nomad Pack to a configured Nomad cluster. + +## Usage + +```plaintext +nomad-pack run [options] +``` + +## Options + +- `-registry=`: Specific registry name containing the pack to be run. +- `-ref=`: Specific Git reference of the pack to retrieve info about. + Supports tags, SHA, and `@latest`. If you do not specify a reference, the + value defaults to `@latest`. Using `ref` with a file path is not supported. +- `-check-index=`: If set, the job is only registered or updated if the + passed job modify index matches the server side version. If you pass a value + of zero, the job is only registered if it does not yet exist. Passing a + non-zero value ensures that the job is being updated from a known state. The + use of this flag is most common in conjunction with `nomad job plan` command. +- `-consul-token=`: If set, the passed Consul token is stored in the job + before sending to the Nomad servers. This allows passing the Consul token + without storing it in the job file. This overrides the token found in the + $CONSUL_HTTP_TOKEN environment variable and that found in the job. +- `-consul-namespace=`: If set, any services in the job are registered + into the specified Consul namespace. Any template block reading from Consul + KV are scoped to the the specified Consul namespace. If Consul ACLs are + enabled and the `allow_unauthenticated` Nomad server Consul configuration is + not enabled, then you must supply a Consul token with appropriate service and + KV Consul ACL policy permissions. +- `-vault-token=`: If set, the passed Vault token is stored in the job + before sending to the Nomad servers. This allows passing the Vault token + without storing it in the job file. This overrides the token found in the + $VAULT_TOKEN environment variable and that found in the job. +- `-vault-namespace=`: If set, the passed Vault namespace is stored in + the job before sending to the Nomad servers. +- `-policy-override`: Sets the flag to force override any soft mandatory + Sentinel policies. +- `-preserve-counts`: If set, the existing task group count is preserved when + updating a job. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +## Examples + +Run an example pack with the default deployment name "example". + +```shell +nomad-pack run example +``` + +Run an example pack with the specified deployment name "dev". + +```shell +nomad-pack run example --name=dev +``` + +Run an example pack with override variables in a variable file. + +```shell +nomad-pack run example --var-file="./overrides.hcl" +``` + +Run an example pack with CLI variable overrides. + +```shell +nomad-pack run example --var="redis_image_version=latest" \ + --var="redis_resources={"cpu": "1000", "memory": "512"}" +``` + +Run a pack under development from the current filesystem. + +```shell +nomad-pack run . +``` diff --git a/website/content/tools/nomad-pack/commands/status.mdx b/website/content/tools/nomad-pack/commands/status.mdx new file mode 100644 index 000000000..4a2df0a1c --- /dev/null +++ b/website/content/tools/nomad-pack/commands/status.mdx @@ -0,0 +1,62 @@ +--- +layout: commands +page_title: nomad-pack status command reference +description: |- + Use the `nomad-pack status` command to fetch information on deployed Nomad packs. +--- + +# nomad-pack status command reference + +Use the `nomad-pack status` command to fetch information on deployed Nomad packs. + +## Usage + +```plaintext +nomad-pack status [options] +``` + +If you do not specify a pack name, the `nomad-pack status` command returns a +list of all deployed packs. If you do specify a pack name, this command returns +a list of all deployed jobs belonging to that pack, along with their status and +deployment names. + +## Options + +- `-registry=`: Specific registry name containing the pack to inspect.If + not specified, the command uses the default registry. +- `-ref=`: Specific Git reference of the pack to retrieve info about. + Supports tags, SHA, and `@latest`. If you do not specify a reference, the + value defaults to `@latest`. Using `ref` with a file path is not supported. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +# Examples + +Get a list of all deployed packs and their registries. + +```shell +nomad-pack status +``` + +Get a list of all deployed jobs in pack example, along with their status +and deployment names. + +```shell +nomad-pack status example +``` + +Get a list of all deployed jobs and their status for an example pack in +the deployment name "dev". + +```shell +nomad-pack status example --name=dev +``` + +Get a list of all deployed jobs and their status for an example pack in +the deployment name "dev". + +```shell +nomad-pack status example --name=dev --registry=community +``` diff --git a/website/content/tools/nomad-pack/commands/stop.mdx b/website/content/tools/nomad-pack/commands/stop.mdx new file mode 100644 index 000000000..5dbf99c55 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/stop.mdx @@ -0,0 +1,63 @@ +--- +layout: commands +page_title: nomad-pack stop command reference +description: |- + Use the `nomad-pack stop` command to stop the specified Nomad Pack in the configured Nomad cluster. +--- + +# nomad-pack stop command reference + +Use the `nomad-pack stop` command to stop the specified Nomad Pack in the configured Nomad cluster. + +By default, the `stop` command stops all jobs in the pack deployment. If you ran +a pack with variable overrides to specify the job name, you must provide the +same variable overrides when stopping the pack to guarantee that this command +targets the correct job in the pack deployment. + +## Usage + +```plaintext +nomad-pack stop [options] +``` + +To delete the pack from the cluster, specify `--purge`, or use the [`nomad-pack +destroy` command](/nomad/tools/nomad-pack/commands/destroy). + +## Options + +- `-registry=`: Specific registry name containing the pack to be + stopped. +- `-ref=`: Specific Git reference of the pack to retrieve info about. + Supports tags, SHA, and `@latest`. If you do not specify a reference, the + value defaults to `@latest`. Using `ref` with a file path is not supported. +- `-purge`: Purge is used to stop a pack and purge it from the system. If not + set, you can still query the pack until the garbage collector purges the pack. +- `-global`: Stop a multi-region pack in all its regions. By default, `pack + stop` only stops a single region at a time. Ignored for single-region jobs. + +@include 'tools/nomad-pack/options-operations.mdx' + +@include 'tools/nomad-pack/options-nomad-cluster.mdx' + +## Examples + +Stop an example pack in deployment "dev". + +```shell +nomad-pack stop example --name=dev +``` + +Stop the `example` pack in deployment "dev" and purge it from the system. + +```shell +nomad-pack stop example --name=dev --purge +``` + +Stop an example pack in deployment "dev" that has a job named "test" +If the same pack has been installed in deployment "dev" but overriding the +job name to "hello", only "test" is stopped. + +```shell +nomad-pack stop example --name=dev --var=job_name=test +``` + diff --git a/website/content/tools/nomad-pack/commands/version.mdx b/website/content/tools/nomad-pack/commands/version.mdx new file mode 100644 index 000000000..a525d97b2 --- /dev/null +++ b/website/content/tools/nomad-pack/commands/version.mdx @@ -0,0 +1,16 @@ +--- +layout: commands +page_title: nomad-pack version command reference +description: |- + Use `nomad-pack version` to return the Nomad Pack version. +--- + +# nomad-pack stop command reference + +Use `nomad-pack version` to return the Nomad Pack version. + +## Usage + +```plaintext +nomad-pack version +``` diff --git a/website/data/tools-nav-data.json b/website/data/tools-nav-data.json index fcce32c78..31a682842 100644 --- a/website/data/tools-nav-data.json +++ b/website/data/tools-nav-data.json @@ -267,6 +267,106 @@ { "title": "Create packs", "path": "nomad-pack/create-packs" + }, + { + "title": "CLI reference", + "routes": [ + { + "title": "Overview", + "path": "nomad-pack/commands" + }, + { + "title": "deps", + "routes": [ + { + "title": "Overview", + "path": "nomad-pack/commands/deps" + }, + { + "title": "vendor", + "path": "nomad-pack/commands/deps/vendor" + } + ] + }, + { + "title": "destroy", + "path": "nomad-pack/commands/destroy" + }, + { + "title": "generate", + "routes": [ + { + "title": "Overview", + "path": "nomad-pack/commands/generate" + }, + { + "title": "pack", + "path": "nomad-pack/commands/generate/pack" + }, + { + "title": "registry", + "path": "nomad-pack/commands/generate/registry" + }, + { + "title": "var-file", + "path": "nomad-pack/commands/generate/var-file" + } + ] + }, + { + "title": "info", + "path": "nomad-pack/commands/info" + }, + { + "title": "list", + "path": "nomad-pack/commands/list" + }, + { + "title": "plan", + "path": "nomad-pack/commands/plan" + }, + { + "title": "registry", + "routes": [ + { + "title": "Overview", + "path": "nomad-pack/commands/registry" + }, + { + "title": "add", + "path": "nomad-pack/commands/registry/add" + }, + { + "title": "delete", + "path": "nomad-pack/commands/registry/delete" + }, + { + "title": "list", + "path": "nomad-pack/commands/registry/list" + } + ] + }, + { + "title": "render", + "path": "nomad-pack/commands/render" + }, + { + "title": "run", + "path": "nomad-pack/commands/run" + }, + { + "title": "status", + "path": "nomad-pack/commands/status" + }, + { + "title": "stop", + "path": "nomad-pack/commands/stop" + }, + { + "title": "version", + "path": "nomad-pack/commands/version" + } + ] } ] }