Get deploy.yaml back from the server
Since 0.7 the server gives back the deploy.yaml that describes what an application runs. It is how a file that was lost, or was never on this machine, is had again. This page shows the command, what comes back for the secret values, why a file with a masked value is refused, and the same from the dashboard and the API.
Before you begin
- The agent and
shipwickare 0.7 or later. An older agent answersthe agent is older than this shipwick and does not write an application's deploy.yaml. - Values that were written in the file come back as they are since 0.8, for an application deployed by a
shipwickand an agent of that version. Before that, every value that is not a reference is masked. - The command takes a token that may deploy the application: the
deployrole, and for a limited token one of its applications. The text around a reference to a secret, and a value that was written in plain sight, are more than a reader is shown elsewhere. - The application has an active deployment.
Print the file
shipwick config my-api # to the terminal
shipwick config my-api -o deploy.yaml # to a file✓ Wrote deploy.yaml: my-api as deployment #7 (1.4.2) runs it
! 1 value is not handed out and stands as "********" in the file: env.API_KEY
Write it again, or store it with shipwick secret set NAME and refer to it as ${NAME}.
Until then shipwick deploy refuses the file.The file is in the layout shipwick init writes, and describes the active deployment. -o does not write over a file that exists: deploy.yaml already exists, with the same command and --force, which overwrites. The lines about values that are not handed out go to standard error, so shipwick config my-api > deploy.yaml writes the file alone.
What comes back for each value
The server does not hand out secret values, and every env value and basic-auth password is one to it unless it was told otherwise. What it does with each depends on how the value arrived.
A value that the deployed file left to the server comes back as exactly that text. With DB_PASSWORD stored by shipwick secret set and this line in the file that was deployed:
env:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/appthe line comes back as it was written. The agent remembers it with the deployment — through redeploys, rollbacks, key rotations, exports and imports — and fills it in again when the file is deployed.
An env value that stood in the deployed file as it was sent comes back as it is, since 0.8: LOG_LEVEL: debug. The agent cannot tell it from a password; shipwick deploy can, because it knows which values it filled in and which it found written, and says so with the deployment. A redeploy and a rollback carry that on.
What is written in deploy.yaml in plain sight is readable by everyone who may deploy the application
A password belongs in ${NAME}, not in the file.
A value that the CLI filled in from the environment or --env-file, even in part, comes back as "********", with a comment on its line, and so does a basic-auth password that was written out. Write the value again, or store it as a secret and write ${NAME}.
# A value shown as "********" was given when the application was deployed and
# is not handed out. Write it again, or store it on the server with
# shipwick secret set NAME and refer to it as ${NAME}. A deployment of this
# file is refused until every such value has been replaced.
name: my-api
image: ghcr.io/company/my-api:1.4.2
port: 8080
replicas: 1
env:
API_KEY: "********" # not handed out: write the value again, or refer to a secret as ${NAME}
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
LOG_LEVEL: debug
proxy:
basic_auth:
- path: /admin
username: mert
password: "********" # not handed out: write the value again, or refer to a secret as ${NAME}
restart:
policy: alwaysThe comment at the top is there only when a value is masked.
Nobody but the sender of a file can say that a value in it is plain, so a value nobody spoke for is masked: every value of an application that was last deployed by a shipwick or an agent older than 0.8, and a value typed into the dashboard's editor. The dashboard keeps the plain values it was shown and that were left as they were. A basic-auth password is never plain, and since 0.10 neither is logging.options.splunk-token: both come back as the mask or as the ${NAME} they were written as.
An application deployed before 0.7
The references were not kept before 0.7. An application that was last deployed by an older agent has all its secret values masked, also the ones that referred to a stored secret, until it is deployed again from its file. After a deployment by 0.7 the password line above reads password: ${ADMIN_PASSWORD}.
A mask cannot be deployed
A file without masks deploys as it is and gives the configuration that runs, with its secrets as they are on the server now.
A file that still has a mask is refused, by shipwick deploy and shipwick validate alike, with the fields that need a value — whoever sends it. "********" is never accepted as an env value or a basic-auth password, so what the server masks cannot be deployed back as if it were the value. The API answers 400 INVALID_CONFIG:
{ "error": { "code": "INVALID_CONFIG", "message": "invalid deploy.yaml",
"details": { "fields": [ {
"field": "env.API_KEY",
"message": "******** is what the server shows in the place of this value, not the value",
"expected": "the value itself, or ${NAME} with the value stored by shipwick secret set NAME" } ] } } }For each masked value there are two ways on:
- Write the value again in the file, where it is not a secret:
REGION: eu-central. Deployed withshipwick deploy, it comes back as written from then on. - Store it on the server and refer to it:
shipwick secret set API_KEY, andAPI_KEY: ${API_KEY}in the file. From then on the file comes back with the reference.
A stored secret may itself hold the text ********; only a value of env or a basic-auth password in a document may not.
In the dashboard
Change the configuration, on an application's Configuration tab, opens the same document: references to stored secrets are references, the values that stood in the deployed file in plain sight are there, and every other secret value stands as "********" and is listed above the document, each with a link that stores it as a secret. The document is checked and deployed from there; one that still holds a mask is refused. A plain value that is left as it was stays plain; one that is changed or typed there is masked from then on, until the file it belongs in is deployed with shipwick deploy.

See Use the dashboard.
From a script
curl -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
https://agent.example.com/api/v1/applications/my-api/configThe answer holds the document, which deployment it describes, masked: the fields whose value is the mask, [] when the document deploys as it is, and since 0.8 plain: the fields whose value was handed out as written. The document goes back unchanged to POST /applications, which deploys the application the document names; ?plain=env.LOG_LEVEL,env.REGION on that request names the values that are to stay plain, and without it every value is masked from then on. See the API reference.
What's next
shipwick configin the CLI reference.- Secrets kept on the server: what a stored secret is, and who may read what.
envand placeholders in thedeploy.yamlreference.- Roll back and redeploy: changing the image without the file.