How to use docker secret ls command to list secrets

Introduction

In this lab, you will learn how to effectively use the docker secret ls command to manage and view secrets within your Docker swarm environment. You will begin by initializing a Docker swarm and creating a sample secret. Subsequently, you will explore how to list all existing secrets, filter the output based on secret names and labels, and finally, format the output of the secret list for better readability and specific information extraction. This hands-on experience will equip you with the skills to efficiently locate and manage your sensitive data stored as Docker secrets.

Skills Graph

List all secrets

In this step, you will learn how to list all secrets in your Docker environment. Docker secrets are used to manage sensitive data, such as passwords, TLS certificates, and SSH keys. They are stored securely in the Docker swarm and can be accessed by services running in the swarm.

Before listing secrets, you need to initialize a Docker swarm. A swarm is a cluster of Docker engines. You can initialize a swarm on a single node for testing purposes.

Open your terminal and run the following command to initialize the swarm:

docker swarm init

You should see output indicating that the swarm has been initialized and that the current node is now a manager.

Now that the swarm is initialized, you can create a secret. We will create a simple secret named my_secret with the value my_secret_value.

Run the following command to create the secret:

echo "my_secret_value" | docker secret create my_secret -

This command takes the string "my_secret_value", pipes it to the docker secret create command, and names the secret my_secret. The hyphen - at the end indicates that the secret value is being read from standard input.

Now, let's list the secrets that exist in your Docker swarm. You can use the docker secret ls command to do this.

Run the following command:

docker secret ls

You should see output similar to this, showing the ID, name, and creation time of the secret you just created:

ID                          NAME        CREATED
<secret_id>                 my_secret   About a minute ago

This command lists all secrets currently managed by your Docker swarm. In the next steps, you will learn how to filter and format this output.

Filter secrets by name

In this step, you will learn how to filter the list of secrets by their name using the docker secret ls command with the --filter flag. This is useful when you have many secrets and want to find a specific one or a group of secrets with similar names.

In the previous step, you created a secret named my_secret. Let's create another secret to demonstrate filtering. We will name this one another_secret.

Run the following command to create the new secret:

echo "another_value" | docker secret create another_secret -

Now, if you run docker secret ls again, you will see both secrets:

docker secret ls

The output will look similar to this, showing both my_secret and another_secret:

ID                          NAME            CREATED
<secret_id_1>               my_secret       About 2 minutes ago
<secret_id_2>               another_secret  About a few seconds ago

To filter the list to show only the secret named my_secret, you can use the --filter name=my_secret option.

Run the following command:

docker secret ls --filter name=my_secret

The output will now only show the secret with the name my_secret:

ID                          NAME        CREATED
<secret_id_1>               my_secret   About 2 minutes ago

You can also use partial names for filtering. For example, to filter for secrets whose names contain "secret", you could use a similar filter, although for exact name matching, the previous command is more precise. The name filter performs an exact match.

This filtering capability is very helpful in environments with a large number of secrets, allowing you to quickly locate the specific secrets you need to work with.

Filter secrets by label

In this step, you will learn how to filter secrets based on labels. Labels are key-value pairs that you can attach to Docker objects, including secrets, to organize and categorize them. Filtering by labels is a powerful way to manage secrets in complex environments.

First, let's create a new secret and add a label to it during creation. We will create a secret named labeled_secret and add the label environment=production.

Run the following command to create the secret with a label:

echo "production_value" | docker secret create --label environment=production labeled_secret -

This command is similar to the previous docker secret create commands, but we've added the --label environment=production flag to attach a label to the secret.

Now, let's create another secret with a different label. We'll name this one dev_secret and give it the label environment=development.

Run the following command:

echo "development_value" | docker secret create --label environment=development dev_secret -

If you list all secrets now using docker secret ls, you will see all three secrets:

docker secret ls

The output will show my_secret, another_secret, labeled_secret, and dev_secret.

To filter the secrets and show only those with the label environment=production, you can use the --filter label=environment=production option.

Run the following command:

docker secret ls --filter label=environment=production

You should see only the labeled_secret in the output:

ID                          NAME            CREATED
<secret_id_3>               labeled_secret  About a minute ago

Similarly, to filter for secrets with the label environment=development, you would use --filter label=environment=development.

Run the following command:

docker secret ls --filter label=environment=development

This will show only the dev_secret:

ID                          NAME        CREATED
<secret_id_4>               dev_secret  About a minute ago

You can also filter for secrets that have a specific label key, regardless of its value, by using --filter label=environment.

Run the following command:

docker secret ls --filter label=environment

This will show both labeled_secret and dev_secret because they both have the environment label key:

ID                          NAME            CREATED
<secret_id_3>               labeled_secret  About 2 minutes ago
<secret_id_4>               dev_secret      About 2 minutes ago

Filtering by labels is a flexible way to manage and retrieve secrets based on your own defined categories.

Format the output of secret list

In this step, you will learn how to format the output of the docker secret ls command using the --format flag. This allows you to customize the information displayed and the way it is presented, which is useful for scripting or generating reports.

By default, docker secret ls outputs a table with columns for ID, NAME, and CREATED. You can change this format using the --format flag with Go template syntax.

For example, to display only the secret names, you can use the format {{.Name}}.

Run the following command:

docker secret ls --format "{{.Name}}"

The output will now list only the names of the secrets, each on a new line:

my_secret
another_secret
labeled_secret
dev_secret

You can also specify multiple fields and format them as a table. For instance, to display the ID and Name separated by a tab, you can use table {{.ID}}\t{{.Name}}. The table keyword ensures the output is aligned in columns.

Run the following command:

docker secret ls --format "table {{.ID}}\t{{.Name}}"

The output will be a table with two columns:

ID                          NAME
<secret_id_1>               my_secret
<secret_id_2>               another_secret
<secret_id_3>               labeled_secret
<secret_id_4>               dev_secret

You can also output the information in JSON format, which is very useful for programmatic processing. Use the format json.

Run the following command:

docker secret ls --format "json"

The output will be a JSON array, where each element represents a secret:

[
  {
    "ID": "<secret_id_1>",
    "Name": "my_secret",
    "CreatedAt": "2023-10-27 10:00:00 +0000 UTC",
    "UpdatedAt": "2023-10-27 10:00:00 +0000 UTC",
    "Labels": {}
  },
  {
    "ID": "<secret_id_2>",
    "Name": "another_secret",
    "CreatedAt": "2023-10-27 10:01:00 +0000 UTC",
    "UpdatedAt": "2023-10-27 10:01:00 +0000 UTC",
    "Labels": {}
  },
  {
    "ID": "<secret_id_3>",
    "Name": "labeled_secret",
    "CreatedAt": "2023-10-27 10:02:00 +0000 UTC",
    "UpdatedAt": "2023-10-27 10:02:00 +0002 UTC",
    "Labels": {
      "environment": "production"
    }
  },
  {
    "ID": "<secret_id_4>",
    "Name": "dev_secret",
    "CreatedAt": "2023-10-27 10:03:00 +0000 UTC",
    "UpdatedAt": "2023-10-27 10:03:00 +0000 UTC",
    "Labels": {
      "environment": "development"
    }
  }
]

The --format flag provides great flexibility in how you view and process information about your Docker secrets.

Summary

In this lab, you learned how to list all secrets in your Docker environment using the docker secret ls command. You started by initializing a Docker swarm and creating a sample secret. You then used docker secret ls to view the ID, name, and creation time of the created secret.

You also learned how to filter the list of secrets by name and label using the --filter flag, and how to format the output of the docker secret ls command for better readability or scripting purposes.