Merge pull request #463 from docker/update/readme

chore: update readme

Author: Benehiko

NOTICE

@@ -0,0 +1,19 @@
+Docker
+Copyright 2012-2026 Docker, Inc.
+
+This product includes software developed at Docker, Inc. (https://www.docker.com).
+
+This product contains software (https://github.com/keybase/go-keychain) developed
+by Keybase, licensed under the MIT License.
+
+The following is courtesy of our legal counsel:
+
+
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws.
+
+For more information, see https://www.bis.doc.gov
+
+See also https://www.apache.org/dev/crypto.html and/or seek legal counsel.

README.md

@@ -4,21 +4,97 @@
 [![lint](https://github.com/docker/secrets-engine/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/docker/secrets-engine/actions/workflows/lint.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-purple)](https://github.com/docker/secrets-engine/blob/main/LICENSE)
 
-## Quickstart
+Secrets Engine and [docker pass](https://docs.docker.com/reference/cli/docker/pass/)
+are bundled with [Docker Desktop](https://docs.docker.com/desktop/).
+A standalone version can also be installed from the [releases](https://github.com/docker/secrets-engine/releases).
 
-Secrets Engine and [docker pass](https://docs.docker.com/reference/cli/docker/pass/) are bundled with [Docker Desktop](https://docs.docker.com/desktop/).
+> [!NOTE]
+> Secret injection in Docker CE is on our roadmap.
 
-Let's store a secret using `docker pass` in the OS Keychain and then inject it
-into a running container using Secrets Engine.
+## Runtime secret injection (no plaintext in your CLI or Compose)
 
-```console
-# Store `Foo` in the OS Keychain
-$ docker pass set Foo=bar
-# Tell docker to use the Secrets Engine using the `se://` URI on an environment variable
-$ docker run --rm -e Foo=se://Foo busybox /bin/sh -c "echo \${Foo}"
-$ bar
+Secrets Engine lets you **reference** secrets in `docker run` / `docker compose`
+and have Docker **resolve and inject** the real values _at runtime_.
+
+**Key idea:** you pass a _pointer_, not the secret.
+
+- In your config (CLI flags / Compose files), you use a `se://` reference like `se://foo`.
+- When the container starts, Docker asks Secrets Engine to resolve that reference
+  and injects the secret into the container.
+- The secret value is sourced from a provider, such as **`docker pass`**, which
+  stores secrets securely in your **local OS keychain** (or from a custom provider plugin).
+
+This means you don’t need:
+
+- host environment variables containing secret values
+- plaintext secret files on disk (such as `.env` files)
+- secret literals embedded in `compose.yaml`
+
+### Example: store once, use everywhere
+
+Store the secret in your OS keychain:
+
+```bash
+docker pass set foo=bar
+```
+
+Run a container using a secret reference (the value se://foo is not the secret itself):
+
+```bash
+docker run --rm -e foo=se://foo busybox sh -c 'echo "$foo"'
+```
+
+Compose example:
+
+```yaml
+services:
+  app:
+    image: your/image
+    environment:
+      API_TOKEN: se://foo
 ```
 
+### Realms (namespace + pattern matching)
+
+Secrets Engine supports **realms**: a simple namespacing scheme that helps to
+organize secrets by purpose, environment, application, or target system, and then retrieve
+them using glob-style patterns.
+
+A realm is a prefix in the secret key. For example:
+
+- `docker/auth/hub/mysecret`
+- `docker/auth/ghcr/token`
+- `docker/db/prod/password`
+
+Because the realm is part of the key, you can query or operate on groups of
+secrets using patterns. For example, to target _all_ Docker auth-related secrets:
+
+- `docker/auth/**`
+
+This makes it easy to:
+
+- keep related secrets grouped together
+- separate environments (e.g. `prod/`, `staging/`, `dev/`)
+- scope listing/lookup operations to a subset of secrets without knowing every
+  key ahead of time
+
+#### Example layout
+
+```text
+docker/
+  auth/
+    hub/
+      mysecret
+    ghcr/
+      token
+  db/
+    prod/
+      password
+```
+
+> [!TIP]
+> Treat realms like paths - predictable structure makes automation and access control much easier.
+
 # Developer Guides
 
 ## How to query secrets
@@ -38,11 +114,16 @@ if err != nil {
 }
 
 // Fetch a secret from the engine
-resp, err := c.GetSecrets(t.Context(), client.MustParsePattern("my-secret"))
+// We are using an exact match here, so only one or zero results will return.
+secrets, err := c.GetSecrets(context.Background(), client.MustParsePattern("my-secret"))
+if errors.Is(err, client.ErrSecretNotFound) {
+    log.Fatalf("no secret found")
+}
+// fallback to generic error
 if err != nil {
     log.Fatalf("failed fetching secrets: %v", err)
 }
-fmt.Println(resp.Value)
+fmt.Println(secrets[0].Value)
 ```
 
 ## How to create a plugin
@@ -62,17 +143,17 @@ var _ plugin.Plugin = &myPlugin{}
 
 type myPlugin struct {
 	m      sync.Mutex
-	secrets map[secrets.ID]string
+	secrets map[plugin.ID]string
 }
 
-func (p *myPlugin) GetSecret(_ context.Context, request secrets.Request) ([]secrets.Envelope, error) {
+func (p *myPlugin) GetSecrets(_ context.Context, pattern plugin.Pattern) ([]plugin.Envelope, error) {
 	p.m.Lock()
 	defer p.m.Unlock()
 
-	var result []secrets.Envelope
+	var result []plugin.Envelope
 	for id, value := range p.secrets {
-		if request.Pattern.Match(id) {
-			result = append(result, secrets.Envelope{
+		if pattern.Match(id) {
+			result = append(result, plugin.Envelope{
 				ID:    id,
 				Value: []byte(value),
 				CreatedAt: time.Now(),
@@ -82,11 +163,11 @@ func (p *myPlugin) GetSecret(_ context.Context, request secrets.Request) ([]secr
 	return result, nil
 }
 
-func (p *myPlugin) Config() plugin.Config {
-	return plugin.Config{
-		Version: "v0.0.1",
-		Pattern: "*",
-	}
+func (p *myPlugin) Run(ctx context.Context) error {
+    // add long-running tasks here
+    // for example, OAuth tokens can be refreshed here.
+	<-ctx.Done()
+	return nil
 }
 ```
 
@@ -99,32 +180,95 @@ package main
 
 import (
 	"context"
+    "fmt"
+	"log/slog"
 
 	"github.com/docker/secrets-engine/plugin"
 )
 
+type myLogger struct{}
+
+func (m *myLogger) Errorf(format string, v ...any) {
+	slog.Error(fmt.Sprintf(format, v...))
+}
+
+func (m *myLogger) Printf(format string, v ...any) {
+	slog.Info(fmt.Sprintf(format, v...))
+}
+
+func (m *myLogger) Warnf(format string, v ...any) {
+	slog.Warn(fmt.Sprintf(format, v...))
+}
+
 func main() {
-    p, err := plugin.New(&myPlugin{secrets: map[secrets.ID]string{"foo": "bar"}})
-    if err != nil {
-        panic(err)
-    }
-	// Run your plugin
-    if err := p.Run(context.Background()); err != nil {
-        panic(err)
+    config := plugin.Config{
+		Version: plugin.MustNewVersion("v0.0.1"),
+		Pattern: plugin.MustParsePattern("myrealm/**"),
+        // custom logger
+		Logger:  &myLogger{},
+	}
+    secrets := map[plugin.ID]string{
+        plugin.MustParseID("myrealm/foo"): "bar",
     }
+	p, err := plugin.New(&myPlugin{secrets: secrets}, config)
+	if err != nil {
+		panic(err)
+	}
+    // Run your plugin
+	if err := p.Run(context.Background()); err != nil {
+		panic(err)
+	}
 }
 ```
 
-### 3. Test and verify the plugin:
+### 3. Query secrets from your plugin:
+
+To verify your plugin works, run the binary and it should connect to the
+Secrets Engine.
 
-The secrets engine is integrated with Docker Desktop.
-To verify your plugin works, run the binary.
-Using the SDK it will automatically connect to the secrets engine in Docker Desktop.
-Then, you can query secrets, e.g. using curl:
+As a quick test we can retrieve secrets using `curl`, when running standalone
+the default socket is `daemon.sock` and with Docker Desktop it is `engine.sock`.
+Below we will query the Secrets Engine in standalone mode.
 
-```console
-$ curl --unix-socket ~/Library/Caches/docker-secrets-engine/engine.sock \
+```bash
+curl --unix-socket ~/Library/Caches/docker-secrets-engine/daemon.sock \
     -X POST http://localhost/resolver.v1.ResolverService/GetSecrets \
-    -H "Content-Type: application/json" -d '{"pattern": "foo"}'
-{"id":"foo","value":"bar","provider":"docker-pass","version":"","error":"","createdAt":"0001-01-01T00:00:00Z","resolvedAt":"2025-08-12T08:25:06.166714Z","expiresAt":"0001-01-01T00:00:00Z"}
+    -H "Content-Type: application/json" \
+    -d '{"pattern": "myrealm/**"}'
 ```
+
+The value of a secret is always encoded into base64.
+When using Go's `json.Unmarshal` it will automatically convert it back into
+a slice of bytes `[]byte`.
+
+To manually decode it, you can pipe the value into `base64`, using the
+flags appropriate for your platform:
+
+```bash
+# macOS / BSD
+echo "<base64 string>" | base64 -D
+
+# GNU/Linux (coreutils)
+echo "<base64 string>" | base64 --decode
+# or
+echo "<base64 string>" | base64 -d
+```
+
+## Legal
+
+_Brought to you courtesy of our legal counsel. For more context,
+see the [NOTICE](https://github.com/docker/secrets-engine/blob/main/NOTICE) document in this repo._
+
+Use and transfer of Docker may be subject to certain restrictions by the
+United States and other governments.
+
+It is your responsibility to ensure that your use and/or transfer does not
+violate applicable laws.
+
+For more information, see https://www.bis.doc.gov
+
+## Licensing
+
+docker/secrets-engine is licensed under the Apache License, Version 2.0. See
+[LICENSE](https://github.com/docker/secrets-engine/blob/main/LICENSE) for the full
+license text.