From 6d833e9753c9e97d5a644831f12f3170c712a0bf Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Thu, 24 Jul 2025 21:38:33 -0300 Subject: [PATCH 1/6] feat: docs update Signed-off-by: Gustavo Carvalho --- docs.json | 275 ++++++++++++++++++ .../externalsecrets/esi-cli/federation.mdx | 1 - .../externalsecrets/esi-cli/flags.mdx | 1 - .../externalsecrets/esi-cli/index.mdx | 1 - .../esi-cli/injection-mechanisms.mdx | 1 - .../externalsecrets/esi-cli/modes.mdx | 1 - .../esi-cli/usage-examples.mdx | 1 - .../federation/authn-authz.mdx | 1 - .../federation/client-setup.mdx | 1 - .../externalsecrets/federation/concepts.mdx | 1 - .../externalsecrets/federation/example.mdx | 1 - .../externalsecrets/federation/index.mdx | 1 - .../federation/server-setup.mdx | 1 - .../externalsecrets/get-started.mdx | 60 ++++ .../pod-webhook/annotations.mdx | 1 - .../externalsecrets/pod-webhook/index.mdx | 1 - .../pod-webhook/installation.mdx | 1 - .../pod-webhook/troubleshooting.mdx | 1 - .../pod-webhook/usage-examples.mdx | 1 - .../{ => tutorials}/dynamic-credentials.mdx | 1 - .../externalsecrets/tutorials/workflows.mdx | 149 ++++++++++ .../externalsecrets/workflows/concepts.mdx | 39 ++- .../externalsecrets/workflows/examples.mdx | 187 ++++++------ .../workflows/introduction.mdx | 17 +- .../externalsecrets/workflows/reference.mdx | 96 ++++-- 25 files changed, 680 insertions(+), 161 deletions(-) create mode 100644 docs.json create mode 100644 docs/enterprise/externalsecrets/get-started.mdx rename docs/enterprise/externalsecrets/{ => tutorials}/dynamic-credentials.mdx (99%) create mode 100644 docs/enterprise/externalsecrets/tutorials/workflows.mdx diff --git a/docs.json b/docs.json new file mode 100644 index 0000000..1fda588 --- /dev/null +++ b/docs.json @@ -0,0 +1,275 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Starter Kit", + "colors": { + "primary": "#7300E5", + "light": "#FFFFFF", + "dark": "#7300E5" + }, + "favicon": "favicon.svg", + "navigation": { + "tabs": [ + { + "tab": "External Secrets Enterprise", + "icon": "key", + "groups": [ + { + "group": "External Secrets Enterprise", + "icon": "key", + "pages": [ + "docs/enterprise/externalsecrets/quickstart", + "docs/enterprise/externalsecrets/get-started", + { + "icon": "lines-leaning", + "group": "Tutorials", + "pages": [ + "docs/enterprise/externalsecrets/tutorials/workflows", + "docs/enterprise/externalsecrets/tutorials/dynamic-credentials" + ] + }, + { + "icon": "wind-turbine", + "group": "Generators", + "pages": [ + "docs/enterprise/externalsecrets/generators/iam-keys", + "docs/enterprise/externalsecrets/generators/neo4j", + "docs/enterprise/externalsecrets/generators/postgresql" + ] + }, + { + "icon": "arrow-progress", + "group": "Workflows", + "pages": [ + "docs/enterprise/externalsecrets/workflows/introduction", + "docs/enterprise/externalsecrets/workflows/concepts", + "docs/enterprise/externalsecrets/workflows/reference", + "docs/enterprise/externalsecrets/workflows/examples", + "docs/enterprise/externalsecrets/workflows/troubleshooting" + ] + }, + { + "icon": "webhook", + "group": "Pod Webhook", + "pages": [ + "docs/enterprise/externalsecrets/pod-webhook/index", + "docs/enterprise/externalsecrets/pod-webhook/installation", + "docs/enterprise/externalsecrets/pod-webhook/annotations", + "docs/enterprise/externalsecrets/pod-webhook/usage-examples", + "docs/enterprise/externalsecrets/pod-webhook/troubleshooting" + ] + }, + { + "icon": "terminal", + "group": "ESI CLI", + "pages": [ + "docs/enterprise/externalsecrets/esi-cli/index", + "docs/enterprise/externalsecrets/esi-cli/modes", + "docs/enterprise/externalsecrets/esi-cli/flags", + "docs/enterprise/externalsecrets/esi-cli/injection-mechanisms", + "docs/enterprise/externalsecrets/esi-cli/federation", + "docs/enterprise/externalsecrets/esi-cli/usage-examples" + ] + }, + { + "icon": "globe", + "group": "Federation", + "pages": [ + "docs/enterprise/externalsecrets/federation/index", + "docs/enterprise/externalsecrets/federation/concepts", + "docs/enterprise/externalsecrets/federation/server-setup", + "docs/enterprise/externalsecrets/federation/client-setup", + "docs/enterprise/externalsecrets/federation/authn-authz", + "docs/enterprise/externalsecrets/federation/example" + ] + } + ] + } + ] + }, + { + "tab": "ESI Agent", + "groups": [ + { + "group": "ESI Agent", + "pages": [ + { + "group": "Getting Started", + "pages": [ + "docs/enterprise/externalsecrets/esi-agent/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + "docs/enterprise/externalsecrets/esi-agent/guides/namespaced-deployments", + "docs/enterprise/externalsecrets/esi-agent/guides/auto-updates" + ] + }, + { + "group": "Reference", + "pages": [ + "docs/enterprise/externalsecrets/esi-agent/reference/api-reference", + "docs/enterprise/externalsecrets/esi-agent/reference/architecture" + ] + }, + "docs/enterprise/externalsecrets/esi-agent/troubleshooting" + ] + } + ] + }, + { + "tab": "Audit", + "groups": [ + { + "group": "Get Started", + "pages": [ + "docs/enterprise/audit/introduction" + ] + }, + { + "group": "Get Started", + "pages": [ + "docs/enterprise/audit/installation" + ] + }, + { + "group": "Dashboard", + "pages": [ + "docs/enterprise/audit/dashboard/lineage", + "docs/enterprise/audit/dashboard/filters" + ] + }, + { + "group": "Destinations", + "pages": [ + "docs/enterprise/audit/destinations/quickstart" + ] + }, + { + "group": "Policies", + "pages": [ + "docs/enterprise/audit/policies/quickstart", + "docs/enterprise/audit/policies/policy-execution-types", + { + "group": "Examples", + "pages": [ + "docs/enterprise/audit/policies/examples/access-compliance", + "docs/enterprise/audit/policies/examples/cross-provider-duplication", + "docs/enterprise/audit/policies/examples/ca-verification", + "docs/enterprise/audit/policies/examples/password-compliance", + "docs/enterprise/audit/policies/examples/rotation-compliance" + ] + } + ] + }, + { + "group": "Listener", + "pages": [ + "docs/enterprise/audit/listener/introduction", + { + "group": "Providers", + "pages": [ + "docs/enterprise/audit/listener/providers/hashicorp-vault", + "docs/enterprise/audit/listener/providers/gcp-secret-manager", + "docs/enterprise/audit/listener/providers/aws-secrets-manager", + "docs/enterprise/audit/listener/providers/aws-parameter-store", + "docs/enterprise/audit/listener/providers/azure-key-vault" + ] + } + ] + }, + { + "group": "Aditional documentation", + "pages": [ + "docs/enterprise/audit/reference/listener-reference", + "docs/enterprise/audit/reference/policy-reference", + "docs/enterprise/audit/reference/troubleshooting" + ] + } + ] + }, + { + "tab": "Reloader", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "docs/open_source/reloader/introduction" + ] + }, + { + "group": "Getting Started", + "pages": [ + "docs/open_source/reloader/quickstart" + ] + }, + { + "group": "Configuration", + "pages": [ + { + "group": "Notification Sources", + "pages": [ + "docs/open_source/reloader/sources/gcp-pubsub-source", + "docs/open_source/reloader/sources/awssqs-source", + "docs/open_source/reloader/sources/vault-source", + "docs/open_source/reloader/sources/azure-eventgrid-source", + "docs/open_source/reloader/sources/webhook-source", + "docs/open_source/reloader/sources/kubernetes-secret-source" + ] + }, + { + "group": "Trigger Destinations", + "pages": [ + "docs/open_source/reloader/destinations/deployments", + "docs/open_source/reloader/destinations/external-secrets" + ] + } + ] + }, + { + "group": "Reference", + "pages": [ + "docs/open_source/reloader/reference/api-reference" + ] + } + ] + } + ] + }, + "logo": { + "light": "/docs/logo/logo-esi-full.svg", + "dark": "/docs/logo/logo-esi-full-white.svg" + }, + "background": { + "color": { + "light": "#ffffff", + "dark": "#030712" + } + }, + "navbar": { + "links": [ + { + "label": "Open Source", + "href": "https://external-secrets.io" + } + ], + "primary": { + "type": "button", + "label": "Back to External Secrets", + "href": "https://externalsecrets.com" + } + }, + "footer": { + "socials": { + "x": "https://x.com/XSecretsInc", + "github": "https://github.com/external-secrets-inc", + "linkedin": "https://www.linkedin.com/company/external-secrets-inc" + } + }, + "integrations": { + "segment": { + "key": "nYHwrLGCNSiWISNZYeXtFSNkGHHnrlWX" + } + } +} \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/esi-cli/federation.mdx b/docs/enterprise/externalsecrets/esi-cli/federation.mdx index d5ca859..890a50a 100644 --- a/docs/enterprise/externalsecrets/esi-cli/federation.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/federation.mdx @@ -1,7 +1,6 @@ --- title: ESI CLI with Federation description: Configure and use esi-cli to fetch secrets from an ESI Federation server. -icon: "network-wired" --- diff --git a/docs/enterprise/externalsecrets/esi-cli/flags.mdx b/docs/enterprise/externalsecrets/esi-cli/flags.mdx index 35385b1..5565291 100644 --- a/docs/enterprise/externalsecrets/esi-cli/flags.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/flags.mdx @@ -1,7 +1,6 @@ --- title: Command-Line Flags description: A comprehensive reference for all esi-cli command-line flags. -icon: "flag" --- diff --git a/docs/enterprise/externalsecrets/esi-cli/index.mdx b/docs/enterprise/externalsecrets/esi-cli/index.mdx index 065a09c..818978a 100644 --- a/docs/enterprise/externalsecrets/esi-cli/index.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Command-Line Interface for External Secrets Operator secret injection and management. -icon: "play" --- diff --git a/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx b/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx index f41b603..7fb2152 100644 --- a/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx @@ -1,7 +1,6 @@ --- title: Secret Injection Mechanisms description: Learn how esi-cli injects secrets as environment variables and files. -icon: "syringe" --- diff --git a/docs/enterprise/externalsecrets/esi-cli/modes.mdx b/docs/enterprise/externalsecrets/esi-cli/modes.mdx index a50a1a7..3a307a2 100644 --- a/docs/enterprise/externalsecrets/esi-cli/modes.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/modes.mdx @@ -1,7 +1,6 @@ --- title: Modes of Operation description: Understand the init and daemon modes of esi-cli. -icon: "toggle-on" --- diff --git a/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx b/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx index c324e77..2ad7ce1 100644 --- a/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx @@ -1,7 +1,6 @@ --- title: Examples description: Practical examples for using esi-cli in different modes. -icon: "books" --- diff --git a/docs/enterprise/externalsecrets/federation/authn-authz.mdx b/docs/enterprise/externalsecrets/federation/authn-authz.mdx index 6069642..186d363 100644 --- a/docs/enterprise/externalsecrets/federation/authn-authz.mdx +++ b/docs/enterprise/externalsecrets/federation/authn-authz.mdx @@ -1,7 +1,6 @@ --- title: Authentication & Authorization description: Delve into the security mechanisms that protect federated secret access. -icon: "lock" --- diff --git a/docs/enterprise/externalsecrets/federation/client-setup.mdx b/docs/enterprise/externalsecrets/federation/client-setup.mdx index a93e03b..e80729f 100644 --- a/docs/enterprise/externalsecrets/federation/client-setup.mdx +++ b/docs/enterprise/externalsecrets/federation/client-setup.mdx @@ -1,7 +1,6 @@ --- title: Federation Client Setup description: Discover how to set up esi-cli and ESE instances as Federation Clients. -icon: "users" --- diff --git a/docs/enterprise/externalsecrets/federation/concepts.mdx b/docs/enterprise/externalsecrets/federation/concepts.mdx index 6936d95..7043451 100644 --- a/docs/enterprise/externalsecrets/federation/concepts.mdx +++ b/docs/enterprise/externalsecrets/federation/concepts.mdx @@ -1,7 +1,6 @@ --- title: Core Concepts description: Understand the fundamental components and ideas behind ESI Federation. -icon: "brain" --- diff --git a/docs/enterprise/externalsecrets/federation/example.mdx b/docs/enterprise/externalsecrets/federation/example.mdx index fb2caa6..debf159 100644 --- a/docs/enterprise/externalsecrets/federation/example.mdx +++ b/docs/enterprise/externalsecrets/federation/example.mdx @@ -1,7 +1,6 @@ --- title: Examples description: Walk through a practical example of setting up and using ESI Federation. -icon: "books" --- diff --git a/docs/enterprise/externalsecrets/federation/index.mdx b/docs/enterprise/externalsecrets/federation/index.mdx index 78d0a26..e0b8400 100644 --- a/docs/enterprise/externalsecrets/federation/index.mdx +++ b/docs/enterprise/externalsecrets/federation/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Securely access secrets across multiple Kubernetes clusters with External Secrets Enterprise Federation. -icon: "play" --- diff --git a/docs/enterprise/externalsecrets/federation/server-setup.mdx b/docs/enterprise/externalsecrets/federation/server-setup.mdx index a952ca4..6ddefaa 100644 --- a/docs/enterprise/externalsecrets/federation/server-setup.mdx +++ b/docs/enterprise/externalsecrets/federation/server-setup.mdx @@ -1,7 +1,6 @@ --- title: Federation Server Setup description: Learn how to configure the Federation Server, including CRDs and API endpoints. -icon: "network-wired" --- diff --git a/docs/enterprise/externalsecrets/get-started.mdx b/docs/enterprise/externalsecrets/get-started.mdx new file mode 100644 index 0000000..797567a --- /dev/null +++ b/docs/enterprise/externalsecrets/get-started.mdx @@ -0,0 +1,60 @@ +--- +title: Get Started +icon: key +--- +import { Accordion, CodeBlock } from '@mintlify/components' + +Welcome to External Secrets Enterprise! This guide will walk you through the process of setting up a local environment to try out the product. + +## Prerequisites +Before you begin, make sure you have the following tools installed: + +- [Docker](https://docs.docker.com/get-docker/) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) +- [Helm](https://helm.sh/docs/intro/install/) + +## Installation + + +First, let's create a local Kubernetes cluster using `kind`: + +```bash +kind create cluster +``` + +This will create a new cluster and configure your `kubectl` to use it. + + + +Now, let's install the External Secrets Enterprise bundle using our Helm chart. This chart includes all the necessary components, including the web UI. + + + The installation bundle is for a Trial License, which is available at https://externalsecrets.com/trial-license. By installing this bundle, you agree to the license terms. + + + +```bash +helm install esi-bundle \ + --namespace esi-bundle \ + --create-namespace \ + --set global.trialLicenseAccepted=true \ + oci://us-central1-docker.pkg.dev/external-secrets-inc-registry/public/charts/esi-bundle +``` + +This command installs the `esi-bundle` chart and all its dependencies, including an ingress controller. + + + +To access the web UI, you need to port-forward the Traefik service that was installed as part of the bundle. Traefik is used as an Ingress controller to expose the UI. + +```bash +kubectl port-forward -n traefik svc/traefik 8080:80 +``` + +Now you can access the UI by opening [http://ui.external-secrets.127.0.0.1.sslip.io:8080](http://ui.external-secrets.127.0.0.1.sslip.io:8080) in your browser. + + + +## Next Steps +Now that you have External Secrets Enterprise up and running, you can start exploring its features. Head over to our [Workflows Tutorial](./tutorials/workflows) to see some use cases and learn how to get the most out of the product. diff --git a/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx b/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx index 0cf383d..babcdb1 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx @@ -1,7 +1,6 @@ --- title: Configuration Overview description: Configure ESI Pod Webhook behavior using pod annotations to inject secrets. -icon: "code" --- diff --git a/docs/enterprise/externalsecrets/pod-webhook/index.mdx b/docs/enterprise/externalsecrets/pod-webhook/index.mdx index 8618a8b..85893fc 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/index.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/index.mdx @@ -1,7 +1,6 @@ --- title: Overview description: Automatically inject External Secrets Operator (ESO) secrets into your pods with the ESI Pod Webhook. -icon: "play" --- The External Secrets Enterprise is product suite is a premium product. diff --git a/docs/enterprise/externalsecrets/pod-webhook/installation.mdx b/docs/enterprise/externalsecrets/pod-webhook/installation.mdx index 92bef7e..202e583 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/installation.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/installation.mdx @@ -1,7 +1,6 @@ --- title: Installation description: Learn how to install the ESI Pod Webhook in your Kubernetes cluster. -icon: "rocket" --- diff --git a/docs/enterprise/externalsecrets/pod-webhook/troubleshooting.mdx b/docs/enterprise/externalsecrets/pod-webhook/troubleshooting.mdx index 797637b..e76abe3 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/troubleshooting.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/troubleshooting.mdx @@ -1,7 +1,6 @@ --- title: Troubleshooting description: Resolve common issues with the ESI Pod Webhook. -icon: "wrench" --- diff --git a/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx b/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx index 1a03166..101259f 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx @@ -1,7 +1,6 @@ --- title: Examples description: Practical examples demonstrating how to use ESI Pod Webhook annotations. -icon: "books" --- The External Secrets Enterprise is product suite is a premium product. diff --git a/docs/enterprise/externalsecrets/dynamic-credentials.mdx b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx similarity index 99% rename from docs/enterprise/externalsecrets/dynamic-credentials.mdx rename to docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx index 45c841e..79147bb 100644 --- a/docs/enterprise/externalsecrets/dynamic-credentials.mdx +++ b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx @@ -1,7 +1,6 @@ --- title: 'Dynamic Credentials' description: 'Use all External Secrets Enterprise features to leverage runtime bound, disposable credentials' -icon: "key" --- The External Secrets Enterprise is product suite is a premium product. diff --git a/docs/enterprise/externalsecrets/tutorials/workflows.mdx b/docs/enterprise/externalsecrets/tutorials/workflows.mdx new file mode 100644 index 0000000..b1c866a --- /dev/null +++ b/docs/enterprise/externalsecrets/tutorials/workflows.mdx @@ -0,0 +1,149 @@ +--- +title: 'Workflow Tutorial' +description: 'A step-by-step guide to using External Secrets Enterprise Workflows.' +--- + +import { CodeBlock } from '@mintlify/components'; + +This tutorial will guide you through a complete workflow in External Secrets Enterprise. You'll learn how to define a reusable workflow, run it on-demand, and schedule it to run periodically. + +### Prerequisites + +Before you begin, you will need: +- A Kubernetes cluster. +- External Secrets Enterprise installed. +- Two `SecretStore` resources named `aws-backend` and `gcp-backend`. You can use any provider, but for this tutorial, we assume these stores exist. + +--- + +## Step 1: Define a Reusable Workflow with `WorkflowTemplate` + +A `WorkflowTemplate` is a reusable blueprint for a series of actions. Here, we'll define a template that generates a strong password and pushes it to a secret store. + +This template has two input parameters: `secretName` and `storeName`, which makes it flexible and reusable for different use cases. + +Save the following manifest as `workflow-template.yaml`: + + +{`apiVersion: workflows.external-secrets.io/v1alpha1 +kind: WorkflowTemplate +metadata: + name: generate-and-push-password +spec: + version: v1alpha1 + name: Generate and Push Password + parameterGroups: + - name: Destination + description: "Where to push the generated secret" + parameters: + - name: secretName + description: "Name of the secret to be created in the target store" + type: string + required: true + - name: storeName + description: "Name of the SecretStore to push the secret to" + type: secretstore + required: true + jobs: + generateAndPush: + standard: + steps: + - name: generatePassword + generator: + kind: Password + spec: + passwordSpec: + length: 32 + digits: 4 + symbols: 4 + outputs: + - name: password + type: string + sensitive: true + - name: pushToStore + push: + destination: + secretStoreRef: + name: "{{ .global.parameters.storeName }}" + data: + - secretKey: password + remoteRef: + key: "{{ .global.jobs.generateAndPush.generatePassword.password }}" + name: "{{ .global.parameters.secretName }}"`} + + +Apply it to your cluster: + + +{`kubectl apply -f workflow-template.yaml`} + + +--- + +## Step 2: Run the Workflow Once with `WorkflowRun` + +A `WorkflowRun` executes a `WorkflowTemplate` a single time. We'll use it to run our password generation template, providing the specific `secretName` and `storeName` as arguments. + +Save the following manifest as `workflow-run.yaml`: + + +{`apiVersion: workflows.external-secrets.io/v1alpha1 +kind: WorkflowRun +metadata: + name: run-password-generation +spec: + templateRef: + name: generate-and-push-password + arguments: + secretName: "my-app-password" + storeName: "aws-backend"`} + + +Apply it to trigger the workflow: + + +{`kubectl apply -f workflow-run.yaml`} + + +You can check the status of the run: + + +{`kubectl get workflowrun run-password-generation -o wide`} + + +--- + +## Step 3: Schedule the Workflow with `WorkflowRunTemplate` + +A `WorkflowRunTemplate` is used to run a workflow on a recurring schedule. Here, we'll schedule our password generation workflow to run every 12 hours, pushing a new password to our `gcp-backend` store. + +Save the following manifest as `scheduled-workflow.yaml`: + + +{`apiVersion: workflows.external-secrets.io/v1alpha1 +kind: WorkflowRunTemplate +metadata: + name: scheduled-password-rotation +spec: + runPolicy: + scheduled: + cron: "0 */12 * * *" + runSpec: + templateRef: + name: generate-and-push-password + arguments: + secretName: "my-rotated-password" + storeName: "gcp-backend"`} + + +Apply it to create the schedule: + + +{`kubectl apply -f scheduled-workflow.yaml`} + + +You can check the status and see the history of runs for the template: + + +{`kubectl describe workflowruntemplate scheduled-password-rotation`} + \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/workflows/concepts.mdx b/docs/enterprise/externalsecrets/workflows/concepts.mdx index 7c74f2e..4bb73b0 100644 --- a/docs/enterprise/externalsecrets/workflows/concepts.mdx +++ b/docs/enterprise/externalsecrets/workflows/concepts.mdx @@ -3,18 +3,35 @@ title: 'Workflow Concepts' description: 'Fundamental concepts behind workflows' --- -## Workflow Architecture +## Core Components -Workflows consist of the following key components: +Workflows are built on three main Kubernetes Custom Resource Definitions (CRDs): -- **Jobs**: Individual units of work that can depend on other jobs -- **Steps**: Atomic operations within a job that perform specific actions -- **Variables**: Data that can be shared between steps and jobs +### WorkflowTemplate -Workflows follow a state machine model with different phases: +A `WorkflowTemplate` is a reusable definition of a workflow. It contains: -- **Pending**: The workflow is waiting to be processed -- **Scheduled**: The workflow is scheduled to run at a future time -- **Running**: The workflow is currently executing -- **Succeeded**: The workflow completed successfully -- **Failed**: The workflow encountered an error and failed \ No newline at end of file +- **Parameters**: A list of input parameters that can be used to customize the workflow at runtime. +- **Jobs**: A map of jobs that define the work to be done. Each job can have one or more steps. +- **Steps**: The individual actions within a job, such as pulling a secret, running a generator, or pushing a secret to a new destination. + +`WorkflowTemplate` resources are designed to be generic and reusable across different environments and use cases. + +### WorkflowRun + +A `WorkflowRun` is an instance of a `WorkflowTemplate`. It is created to execute a workflow with a specific set of arguments. It contains: + +- **`templateRef`**: A reference to the `WorkflowTemplate` to be executed. +- **`arguments`**: A set of key-value pairs that provide values for the parameters defined in the `WorkflowTemplate`. + +A `WorkflowRun` is a one-time execution of a workflow. Once it completes, it will not run again. + +### WorkflowRunTemplate + +A `WorkflowRunTemplate` is a controller that automates the creation of `WorkflowRun` resources. It allows you to run workflows on a schedule or in response to changes. It contains: + +- **`runSpec`**: A `WorkflowRunSpec` that defines the `WorkflowRun` to be created. +- **`runPolicy`**: A policy that determines when to create a new `WorkflowRun`. The following policies are supported: + - **`once`**: Creates a `WorkflowRun` only once. + - **`scheduled`**: Creates `WorkflowRun` resources on a schedule, defined by a `cron` expression or a fixed `every` interval. + - **`onChange`**: Creates a `WorkflowRun` whenever the `WorkflowRunTemplate` spec changes. \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/workflows/examples.mdx b/docs/enterprise/externalsecrets/workflows/examples.mdx index 670d861..94c28e5 100644 --- a/docs/enterprise/externalsecrets/workflows/examples.mdx +++ b/docs/enterprise/externalsecrets/workflows/examples.mdx @@ -3,119 +3,102 @@ title: 'Workflow Examples' description: 'Complete and annotated workflow examples' --- -## Complete Example +import { CodeBlock } from '@mintlify/components'; -```yaml -apiVersion: external-secrets.io/v1alpha1 -kind: Workflow -metadata: - name: push-to-multiple-stores - annotations: - workflows.external-secrets.io/description: "Workflow that pushes generated secrets to multiple stores" -spec: - version: v1alpha1 - name: push-to-multiple-stores - jobs: - generateSecret: - standard: - steps: - - name: generateApiKey +This page provides examples for `WorkflowTemplate`, `WorkflowRun`, and `WorkflowRunTemplate`. + +## 1. WorkflowTemplate + +This example defines a `WorkflowTemplate` that generates a password and pushes it to a specified secret store. + + +{` +--- + apiVersion: workflows.external-secrets.io/v1alpha1 + kind: WorkflowTemplate + metadata: + name: generate-and-push-password + spec: + version: v1alpha1 + name: Generate and Push Password + parameterGroups: + - name: Destination + description: "Where to push the generated secret" + parameters: + - name: secretName + description: "Name of the secret to be created in the target store" + type: string + required: true + - name: storeName + description: "Name of the SecretStore to push the secret to" + type: secretstore + required: true + jobs: + generateAndPush: + standard: + steps: + - name: generatePassword generator: kind: Password spec: passwordSpec: - length: 42 - digits: 5 - symbols: 5 - symbolCharacters: "-_$@" - noUpper: false - allowRepeat: true + length: 32 + digits: 4 + symbols: 4 outputs: - name: password type: string sensitive: true - - createSecret: - dependsOn: - - generateSecret - standard: - steps: - - name: createSecret - transform: - mappings: - api_key: "{{ .global.jobs.generateSecret.generateApiKey.password }}" - outputs: - - name: api_key - type: string - sensitive: true - - - name: createTargets - javascript: - script: | - // Create an array to specify target stores - setArray('targetStores', ['gcp-store', 'aws-store']) - - // Set environment variable for conditional job - setString('environment', 'production') - outputs: - - name: targetStores - type: map - - name: environment - type: string - - selectEnvironment: - dependsOn: - - createSecret - conditional: - branches: - - condition: "{{ eq .global.jobs.createSecret.createTargets.environment \"production\" }}" - steps: - - name: productionConfig - transform: - mappings: - retention_days: "90" - log_level: "error" - - - condition: "{{ eq .global.jobs.createSecret.createTargets.environment \"staging\" }}" - steps: - - name: stagingConfig - transform: - mappings: - retention_days: "30" - log_level: "info" - - - condition: "{{ eq .global.jobs.createSecret.createTargets.environment \"development\" }}" - steps: - - name: devConfig - transform: - mappings: - retention_days: "7" - log_level: "debug" - - pushToStores: - dependsOn: - - createSecret - - selectEnvironment - loop: - concurrency: 0 - range: "{{ .global.jobs.createSecret.createTargets.targetStores }}" - steps: - - name: push + - name: pushToStore push: - secretSource: ".global.jobs.createSecret.createSecret" destination: - storeRef: - name: "{{ .range.value }}" - kind: SecretStore + secretStoreRef: + name: "{{ .global.parameters.storeName }}" data: - - match: - secretKey: "api_key" - remoteRef: - remoteKey: "new-secret" - property: "api_key" -``` + - secretKey: password + remoteRef: + key: "{{ .global.jobs.generateAndPush.generatePassword.password }}" + name: "{{ .global.parameters.secretName }}"`} + -Apply this workflow to your cluster: +## 2. WorkflowRun -```bash -kubectl apply -f push-to-multiple-stores.yaml \ No newline at end of file +This example shows how to create a `WorkflowRun` to execute the `generate-and-push-password` template once. + + +{` +--- + apiVersion: workflows.external-secrets.io/v1alpha1 + kind: WorkflowRun + metadata: + name: run-password-generation + spec: + templateRef: + name: generate-and-push-password + arguments: + secretName: "my-app-password" + storeName: "aws-backend"`} + + +## 3. WorkflowRunTemplate + +This example uses a `WorkflowRunTemplate` to run the same workflow on a schedule (every 12 hours). + + +{` +--- + apiVersion: workflows.external-secrets.io/v1alpha1 + kind: WorkflowRunTemplate + metadata: + name: scheduled-password-rotation + spec: + runPolicy: + scheduled: + cron: "0 */12 * * *" + runSpec: + templateRef: + name: generate-and-push-password + arguments: + secretName: "my-rotated-password" + storeName: "gcp-backend"`} + \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/workflows/introduction.mdx b/docs/enterprise/externalsecrets/workflows/introduction.mdx index f0b7419..cb01b3d 100644 --- a/docs/enterprise/externalsecrets/workflows/introduction.mdx +++ b/docs/enterprise/externalsecrets/workflows/introduction.mdx @@ -1,19 +1,16 @@ --- -title: 'Workflows' +title: 'Introduction' description: 'Automate secret management with External Secrets Enterprise workflows' --- - Workflows in External Secrets Enterprise provide a powerful way to orchestrate complex secret management operations through a series of jobs and steps. Use workflows to pull, generate, transform, and push secrets across providers in a declarative DAG-based model. + Workflows in External Secrets Enterprise provide a powerful way to orchestrate complex secret management operations. Use workflows to pull, generate, transform, and push secrets across providers in a declarative, DAG-based model. -Workflows allow you to define a directed acyclic graph (DAG) of jobs and steps, enabling advanced orchestration patterns: +The workflow system is built around three core components: -- Scheduling: Run workflows on a fixed schedule or using cron expressions. -- Generators: Use built-in generators to create new secrets. -- Pull Steps: Retrieve secrets from external providers. -- Transform Steps: Modify and map data using Go templates. -- Push Steps: Deliver secrets to target stores. -- JavaScript Steps: Execute custom logic in-line. +- **WorkflowTemplate:** A reusable blueprint that defines the structure and logic of your workflow, including jobs, steps, and parameters. +- **WorkflowRun:** An instance of a `WorkflowTemplate` that executes the defined jobs and steps with a specific set of arguments. +- **WorkflowRunTemplate:** A controller that automates the creation of `WorkflowRun` resources based on a schedule (cron or interval) or in response to changes. -Each workflow run provides detailed status and output visibility, helping you troubleshoot and optimize secret management processes. \ No newline at end of file +This separation of concerns allows you to define complex, reusable workflows and trigger them in a variety of ways. Each workflow run provides detailed status and output visibility, helping you troubleshoot and optimize your secret management processes. \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/workflows/reference.mdx b/docs/enterprise/externalsecrets/workflows/reference.mdx index 15522fa..11f49e0 100644 --- a/docs/enterprise/externalsecrets/workflows/reference.mdx +++ b/docs/enterprise/externalsecrets/workflows/reference.mdx @@ -3,23 +3,79 @@ title: 'Workflow API Reference' description: 'Detailed reference for the Workflow CRD schema' --- -## Schema Overview - -| Field | Type | Description | -|---------------------------|----------------------|-----------------------------------------------------| -| `apiVersion` | string | Kubernetes API version | -| `kind` | string | Resource kind: Workflow | -| `metadata` | object | Standard resource metadata | -| `spec.version` | string | API version of the workflow spec | -| `spec.name` | string | Name of the workflow | -| `spec.schedule.every` | string | Interval schedule (e.g., `"1h"`) | -| `spec.schedule.cron` | string | Cron expression schedule | -| `spec.jobs` | map[string]JobSpec | Map of job definitions | -| `spec.jobs[].standard` | StandardJobSpec | Standard job with sequential steps | -| `spec.jobs[].loop` | LoopJobSpec | Loop job configuration | -| `spec.jobs[].conditional` | ConditionalJobSpec | Conditional job branches | -| `spec.jobs[].dependsOn` | []string | List of dependent job names | -| `spec.jobs[].steps` | []Step | Sequence of step definitions | -| `status.phase` | string | Current workflow phase (Pending, Running, etc.) | - -For the complete schema and field details, see the [Workflow API spec](https://github.com/external-secrets-inc/external-secrets/blob/main/docs/api/workflow.md). \ No newline at end of file +This page provides a detailed reference for the `WorkflowTemplate`, `WorkflowRun`, and `WorkflowRunTemplate` Custom Resource Definition (CRD) schemas. + +## WorkflowTemplate + +A `WorkflowTemplate` is a reusable blueprint for a workflow. + +### WorkflowTemplateSpec + +| Field | Type | Description | +|---|---|---| +| `version` | string | The version of the workflow template schema. | +| `name` | string | A human-readable name for the workflow template. | +| `parameterGroups` | []ParameterGroup | A list of parameter groups that can be overridden at runtime. | +| `jobs` | map[string]Job | A map of job definitions that constitute the workflow. | + +#### Parameter + +| Field | Type | Description | +|---|---|---| +| `name` | string | The name of the parameter. | +| `description` | string | A human-readable description of the parameter. | +| `type` | ParameterType | The data type of the parameter (e.g., `string`, `secretstore`, `generator[fake]`). | +| `required` | boolean | Specifies whether the parameter is mandatory. | +| `default` | string | The default value for the parameter if not provided. | +| `allowMultiple` | boolean | Allows multiple values for the parameter, treating it as an array. | +| `resourceConstraints` | ResourceConstraints | Constraints for resource selection (e.g., for `secretstore` type). | +| `validation` | ParameterValidation | Validation rules, such as `minItems` and `maxItems` for arrays. | + +## WorkflowRun + +A `WorkflowRun` is an instance of a `WorkflowTemplate` that executes the defined jobs. + +### WorkflowRunSpec + +| Field | Type | Description | +|---|---|---| +| `templateRef` | object | A reference to the `WorkflowTemplate` to execute. Must contain a `name` field. | +| `arguments` | object | A map of key-value pairs for the template parameters. Keys must match parameter names. | + +### WorkflowRunStatus + +| Field | Type | Description | +|---|---|---| +| `workflowRef` | object | A reference to the underlying `Workflow` resource created by the run. | +| `conditions` | []metav1.Condition | The latest observations of the `WorkflowRun`'s state. | +| `phase` | string | The current phase of the run (`Pending`, `Running`, `Succeeded`, `Failed`). | +| `startTime` | metav1.Time | The time when the workflow run started. | +| `completionTime` | metav1.Time | The time when the workflow run completed. | + +## WorkflowRunTemplate + +A `WorkflowRunTemplate` automates the creation of `WorkflowRun` resources. + +### WorkflowRunTemplateSpec + +| Field | Type | Description | +|---|---|---| +| `runSpec` | WorkflowRunSpec | The specification for the `WorkflowRun` to be created. | +| `runPolicy` | RunPolicy | The policy that determines when to create a new `WorkflowRun`. | +| `revisionHistoryLimit` | int | The number of `WorkflowRun` resources to retain for history. Defaults to 3. | + +#### RunPolicy + +| Field | Type | Description | +|---|---|---| +| `once` | object | Creates a `WorkflowRun` only once. This is an empty object `{}`. | +| `scheduled` | object | Creates `WorkflowRun` resources on a schedule. Contains a `cron` field with a cron expression. | +| `onChange` | object | Creates a `WorkflowRun` whenever the `WorkflowRunTemplate` spec changes. This is an empty object `{}`. | + +### WorkflowRunTemplateStatus + +| Field | Type | Description | +|---|---|---| +| `lastRunTime` | metav1.Time | The timestamp of the last `WorkflowRun` execution. | +| `runStatuses` | []NamedWorkflowRunStatus | A list of statuses for recent `WorkflowRun` resources. | +| `conditions` | []metav1.Condition | The latest observations of the `WorkflowRunTemplate`'s state. | \ No newline at end of file From 325c9db33a208c2c6b89092b0a5d2cb2fd8dbf1d Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Fri, 25 Jul 2025 09:49:51 -0300 Subject: [PATCH 2/6] feat: more docs Signed-off-by: Gustavo Carvalho --- docs.json | 20 +- .../externalsecrets/introduction.mdx | 30 +++ .../enterprise/externalsecrets/quickstart.mdx | 20 -- .../externalsecrets/scan/introduction.mdx | 75 ++++++ .../externalsecrets/targets/eso-vm-server.mdx | 54 ++++ .../externalsecrets/targets/index.mdx | 21 ++ .../targets/virtual-machine.mdx | 50 ++++ .../tutorials/dynamic-credentials.mdx | 2 +- .../workflows/preset-workflows.mdx | 87 +++++++ mint.json | 233 ------------------ 10 files changed, 337 insertions(+), 255 deletions(-) create mode 100644 docs/enterprise/externalsecrets/introduction.mdx delete mode 100644 docs/enterprise/externalsecrets/quickstart.mdx create mode 100644 docs/enterprise/externalsecrets/scan/introduction.mdx create mode 100644 docs/enterprise/externalsecrets/targets/eso-vm-server.mdx create mode 100644 docs/enterprise/externalsecrets/targets/index.mdx create mode 100644 docs/enterprise/externalsecrets/targets/virtual-machine.mdx create mode 100644 docs/enterprise/externalsecrets/workflows/preset-workflows.mdx delete mode 100644 mint.json diff --git a/docs.json b/docs.json index 1fda588..4e3f6ee 100644 --- a/docs.json +++ b/docs.json @@ -18,7 +18,7 @@ "group": "External Secrets Enterprise", "icon": "key", "pages": [ - "docs/enterprise/externalsecrets/quickstart", + "docs/enterprise/externalsecrets/introduction", "docs/enterprise/externalsecrets/get-started", { "icon": "lines-leaning", @@ -34,6 +34,7 @@ "pages": [ "docs/enterprise/externalsecrets/generators/iam-keys", "docs/enterprise/externalsecrets/generators/neo4j", + "docs/enterprise/externalsecrets/generators/openai", "docs/enterprise/externalsecrets/generators/postgresql" ] }, @@ -43,11 +44,28 @@ "pages": [ "docs/enterprise/externalsecrets/workflows/introduction", "docs/enterprise/externalsecrets/workflows/concepts", + "docs/enterprise/externalsecrets/workflows/preset-workflows", "docs/enterprise/externalsecrets/workflows/reference", "docs/enterprise/externalsecrets/workflows/examples", "docs/enterprise/externalsecrets/workflows/troubleshooting" ] }, + { + "icon": "bullseye-arrow", + "group": "Targets", + "pages": [ + "docs/enterprise/externalsecrets/targets/index", + "docs/enterprise/externalsecrets/targets/virtual-machine", + "docs/enterprise/externalsecrets/targets/eso-vm-server" + ] + }, + { + "icon": "radar", + "group": "Scanning and Findings", + "pages": [ + "docs/enterprise/externalsecrets/scan/introduction" + ] + }, { "icon": "webhook", "group": "Pod Webhook", diff --git a/docs/enterprise/externalsecrets/introduction.mdx b/docs/enterprise/externalsecrets/introduction.mdx new file mode 100644 index 0000000..927bfcf --- /dev/null +++ b/docs/enterprise/externalsecrets/introduction.mdx @@ -0,0 +1,30 @@ +--- +title: 'Introduction' +description: 'Facilitating Secrets Management with ESI distribution of ESO' +icon: "play" +--- + + The External Secrets Enterprise is product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + +External Secrets Enterprise is an Enterprise Distribution of External Secrets Operator. + +It includes several features over the Open Source version, including: + +* All [External Secrets Operator](https://external-secrets.io) Features +* Custom [Generators](/docs/enterprise/externalsecrets/generators/index) +* Custom [Secret Stores](/docs/enterprise/externalsecrets/targets/index) +* [Workflow Automation](/docs/enterprise/externalsecrets/workflows/introduction) +* [Secrets Discovery](/docs/enterprise/externalsecrets/scan/introduction) +* [Federation between clusters](/docs/enterprise/externalsecrets/federation/introduction) +* Pod injection via [Webhook](/docs/enterprise/externalsecrets/pod-webhook/index) and [helper CLI](/docs/enterprise/externalsecrets/esi-cli/index) + +Other features available within the External Secrets Enterprise ecossystem include: +* [Compliance Audit](/docs/enterprise/audit/introduction) for Credentials +* [Automatic Workload Reload](/docs/open_source/reloader/introduction) + +## Get Started +You can get started with External Secrets Enterprise with two ways: +* As part of [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) default configuration, the Enterprise Distribution of ESO is automatically distributed & managed within your environments. +* Using our [bundle helm charts](/docs/enterprise/externalsecrets/get-started) diff --git a/docs/enterprise/externalsecrets/quickstart.mdx b/docs/enterprise/externalsecrets/quickstart.mdx deleted file mode 100644 index 719af81..0000000 --- a/docs/enterprise/externalsecrets/quickstart.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: 'Introduction' -description: 'Facilitating Secrets Management with ESI distribution of ESO' -icon: "play" ---- - - The External Secrets Enterprise is product suite is a premium product. - It requires a specific subscription. Contact us for more information. - - -As part of [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) default configuration, the Enterprise Distribution of -External Secrets Operator (ESI for ESO) is automatically used within your environments. - -It has many features, including: -* All [External Secrets Operator](https://external-secrets.io) Features -* Custom Generators -* Custom Secret Stores (_coming soon_) -* Automatic Deployments Reloading (_coming soon_) - -In this page you'll find more information on how to configure and use Enterprise-Exclusive features of ESO. \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/scan/introduction.mdx b/docs/enterprise/externalsecrets/scan/introduction.mdx new file mode 100644 index 0000000..140bf68 --- /dev/null +++ b/docs/enterprise/externalsecrets/scan/introduction.mdx @@ -0,0 +1,75 @@ +# Scanning and Findings + +External Secrets Enterprise provides a powerful scanning feature to help you identify and manage secrets across your infrastructure. This is particularly useful for discovering where secrets are being used and identifying potential duplicates or misconfigurations. + +## How it Works + +The scanning process is driven by the `Job` resource (`scan.external-secrets.io/Job`), which defines the scope and frequency of a scan. When a scan job is executed, it searches for secrets within the all `SecretStores` and `Targets` available in its namespace. +The Job will create `Finding` resources for any discovered items across multiple locations (`SecretStore` and `Target`). + + + + 1. A `Job` resource is created to define the scan parameters. + 2. The job runs according to its `runPolicy`. + 3. During the scan, if a secret is found, a corresponding `Finding` resource is created. + 4. You can review the `Finding` resources to understand where your secrets are located. + + + +## The `Job` Resource + +The `Job` resource is the core component of the scanning feature. It allows you to configure how and where the scan should be performed. + +Here is an example of a `Job` resource: + +```yaml +apiVersion: scan.external-secrets.io/v1alpha1 +kind: Job +metadata: + name: daily-vm-scan +spec: + runPolicy: Poll + interval: 24h + constraints: + targetConstraints: + - kind: VirtualMachine + apiVersion: targets.external-secrets.io/v1alpha1 + matchLabels: + environment: production +``` + +### Job Specification + +- `runPolicy`: Defines when the job should run. It can be `Poll` (at a regular interval), `OnChange` (when a related resource changes), or `Once`. +- `interval`: If the `runPolicy` is `Poll`, this field specifies the time between scans. +- `constraints`: This field allows you to limit the scan to specific `SecretStores` or `Targets` using label selectors. + +## The `Finding` Resource + +A `Finding` resource is created for each unique secret discovered during a scan. It contains information about the secret, including its hash and the locations where it was found. + +Here is an example of a `Finding` resource: + +```yaml +apiVersion: scan.external-secrets.io/v1alpha1 +kind: Finding +metadata: + name: finding-abcde +spec: + hash: "a1b2c3d4e5..." +status: + locations: + - secretStore: + name: aws-secrets-manager + remoteRef: + remoteKey: /production/database/credentials + - target: + kind: VirtualMachine + name: prod-web-server-1 + remoteRef: + remoteKey: /etc/app/secrets/db.conf +``` + +By examining the `Finding` resources, you can gain valuable insights into your secret landscape and take action to remediate any issues, such as rotating credentials or removing duplicates. + +You can also leverage the `Finding` or the `Location` information from a finding to automate synchronization by leveraging [Workflows](./workflows/introduction) \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/targets/eso-vm-server.mdx b/docs/enterprise/externalsecrets/targets/eso-vm-server.mdx new file mode 100644 index 0000000..e656539 --- /dev/null +++ b/docs/enterprise/externalsecrets/targets/eso-vm-server.mdx @@ -0,0 +1,54 @@ +# External Secrets Operator VM Server + +`eso-vm-server` is a small API server that runs on a Virtual Machine to enable it as a Target for External Secrets Operator. It allows for scanning the VM for secrets and for receiving secret updates. + +## Installation + +To use the `eso-vm-server`, you need to run the binary on your Virtual Machine. You can build it from source or use a pre-compiled binary if available. + +### Building from Source + +1. **Clone the repository:** + + ```bash + git clone # Replace with the actual repository URL + cd vm_server + ``` + +2. **Build the binary:** + + ```bash + go build -o eso-vm-server main.go + ``` + +## Running the Server + +Once you have the binary, you can run it with the following command: + +```bash +./eso-vm-server --port 8080 +``` + +### TLS Configuration + +For a secure setup, it is highly recommended to run the server with mTLS. You can do this by providing the necessary TLS flags: + +```bash +./eso-vm-server \ + --port 1323 \ + --ca-file /path/to/ca.crt \ + --cert-file /path/to/server.crt \ + --key-file /path/to/server.key +``` + + + When using mTLS, ensure that the client certificates are properly configured in your `VirtualMachine` manifest to allow External Secrets Operator to communicate with the `eso-vm-server`. + + +## API Endpoints + +The `eso-vm-server` exposes the following API endpoints: + +- `POST /api/v1/scan`: Initiates a scan on the Virtual Machine. +- `GET /api/v1/scan/:id`: Retrieves the status of a specific scan. +- `POST /api/v1/secrets/:id/version`: Creates or updates a secret on the Virtual Machine. diff --git a/docs/enterprise/externalsecrets/targets/index.mdx b/docs/enterprise/externalsecrets/targets/index.mdx new file mode 100644 index 0000000..195aec4 --- /dev/null +++ b/docs/enterprise/externalsecrets/targets/index.mdx @@ -0,0 +1,21 @@ +# Targets + +Targets are external systems that can receive and be updated with secrets managed by External Secrets Operator. This allows you to securely push secrets to various destinations, such as a Virtual Machine. + +## How it Works + +The `PushSecret` resource is used to define how secrets are pushed to a target. It specifies the source of the secret, the target destination, and the update policy. + +On that Regard, A `Target` works similarly to a `SecretStore`, however they also support a `Scan` ability to map out which credentials are being used, and where. + + + A `PushSecret` can be used to push secrets to any provider that is configured as a `SecretStore`. + + +This section will guide you through configuring different types of targets. + +## Available Targets + +The following Targets are available within External Secrets Enterprise: + +* [Virtual Machine](./virtual-machine) - Allows you to Scan and Update Credentials on VMs diff --git a/docs/enterprise/externalsecrets/targets/virtual-machine.mdx b/docs/enterprise/externalsecrets/targets/virtual-machine.mdx new file mode 100644 index 0000000..205e2c6 --- /dev/null +++ b/docs/enterprise/externalsecrets/targets/virtual-machine.mdx @@ -0,0 +1,50 @@ +# Virtual Machine Target + +This guide explains how to configure a Virtual Machine as a target for your secrets. + +## Prerequisites + +In order to use the `VirtualMachine` Target, you must install and run the [`eso-vm-server`](./eso-vm-server) on the Virtual Machine you want to add. + +## Configuration + +To push a secret to a Virtual Machine, you need to create a `PushSecret` or a `Workflow` resource. + Here is an example that pushes a secret to a specific location on the VM: + + + + You can only Push a Secret to a VM after that Secret has been already Scanned. + The Scanning process is done by External Secrets Enterprise via a `scan.external-secrets.io/Job` Resource. + For more information, please see [Scanning and Findings](./scan/introduction). + + +```yaml +apiVersion: external-secrets.io/v1alpha1 +kind: PushSecret +metadata: + name: vm-secret-push +spec: + refreshInterval: "1h" + secretStoreRefs: + - name: your-secret-store # Replace with your SecretStore name + kind: SecretStore + selector: + secret: + name: my-secret # The Kubernetes secret to push + data: + - match: + secretKey: "api-key" + remoteRef: + remoteKey: "/etc/secrets/api-key" +``` + + + + - `refreshInterval`: How often to check for secret updates. + - `secretStoreRefs`: A reference to the `SecretStore` that provides the secrets. + - `selector`: Specifies which Kubernetes secret to push. + - `data`: Defines the mapping between the Kubernetes secret key and the remote path on the Virtual Machine. + + + +This configuration will take the value of the `api-key` from the `my-secret` Kubernetes secret and write it to the file `/etc/secrets/api-key` on the Virtual Machine that is associated with the specified `SecretStore`. diff --git a/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx index 79147bb..ef0ffc5 100644 --- a/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx +++ b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx @@ -48,7 +48,7 @@ Let's illustrate with an example where a Pod needs temporary credentials from Ha **Step 1: Define and Install a `Generator`** -Create a `Generator` CR on the ESE Federation Server. This example uses a hypothetical `VaultDynamicSecretGenerator` that leverages an existing ESE `SecretStore` (which points to Vault) to generate credentials. +Create a `Generator` Custom Resource on the ESE Federation Server. This example uses a hypothetical `VaultDynamicSecretGenerator` that leverages an existing ESE `SecretStore` (which points to Vault) to generate credentials. ```yaml # On the ESE Federation Server cluster diff --git a/docs/enterprise/externalsecrets/workflows/preset-workflows.mdx b/docs/enterprise/externalsecrets/workflows/preset-workflows.mdx new file mode 100644 index 0000000..b8f27f6 --- /dev/null +++ b/docs/enterprise/externalsecrets/workflows/preset-workflows.mdx @@ -0,0 +1,87 @@ +# Preset Workflows + +External Secrets Enterprise comes with a set of preset workflow templates that you can use to automate common secret management tasks. These templates are automatically available in your cluster when you install External Secrets Enterprise. +The Preset Workflow Templates are created on `eso-server` namespace. + + + You can use these templates as a starting point and customize them to fit your specific needs. + + +## Available Workflows + + + + This workflow distributes a secret from a source location to multiple target locations. + It is particularly useful for synchronizing secrets that have been identified as duplicates by a scan job. + + Use this Workflow when you want to react to a change on a given Source of Truth. + Whenever the value in the source is changed, this Workflow will distribute it to the selected Target Locations. + + **Mandatory Parameters:** + - `sourceLocation` (`secretlocation`): The source secret to be distributed. + - `targetLocations` (`array[secretlocation]`): A list of destination locations. + + To inspect the full template, run the following command: + ```bash + kubectl get workflowtemplate distribute-between-locations -n eso-server -o yaml + ``` + + + This workflow generates a new secret using a specified generator and then distributes it to multiple secret stores. + + Use this Workflow when you want External Secrets Enterprise to handle rotation on a given time frame. + + **Mandatory Parameters:** + - `generator` (`generator[any]`): The generator to use for creating the secret. + - `storesToDistribute` (`array[secretstore]`): A list of `SecretStore` destinations. + - `keyToDistribute` (`string`): The name of the secret key to be created in the destination stores. + + To inspect the full template, run the following command: + ```bash + kubectl get workflowtemplate generate-and-distribute-workflow -n eso-server -o yaml + ``` + + + This workflow is designed to distribute secrets that are in JSON format from a source `SecretStore` to multiple destination `SecretStore`s. + + Use this Workflow when you want to distribute a JSON secret to multiple locations - preserving the JSON format. + + **Mandatory Parameters:** + - `store` (`secretstore`): The source `SecretStore`. + - `keyToDistribute` (`string`): The key of the JSON secret to distribute. + - `storesToDistribute` (`array[secretstore]`): A list of destination `SecretStore`s. + + To inspect the full template, run the following command: + ```bash + kubectl get workflowtemplate json-distribution-workflow -n eso-server -o yaml + ``` + + + This workflow finds secrets in a `SecretStore` that match a regular expression and distributes them to multiple other `SecretStore`s. + + Use this Workflow when you want to distribute multiple secrets to multiple locations on a raw value. + + **Mandatory Parameters:** + - `store` (`secretstore`): The source `SecretStore`. + - `pattern` (`string`): The regular expression to match secret names. + - `storesToDistribute` (`array[secretstore]`): A list of destination `SecretStore`s. + + To inspect the full template, run the following command: + ```bash + kubectl get workflowtemplate multiple-distribution-workflow -n eso-server -o yaml + ``` + + + This is a basic workflow for distributing a single secret of any format from one `SecretStore` to many others. + + **Mandatory Parameters:** + - `store` (`secretstore`): The source `SecretStore`. + - `keyToDistribute` (`string`): The key of the secret to distribute. + - `storesToDistribute` (`array[secretstore]`): A list of destination `SecretStore`s. + + To inspect the full template, run the following command: + ```bash + kubectl get workflowtemplate distribution-workflow -n eso-server -o yaml + ``` + + diff --git a/mint.json b/mint.json deleted file mode 100644 index e8d5694..0000000 --- a/mint.json +++ /dev/null @@ -1,233 +0,0 @@ -{ - - "$schema": "https://mintlify.com/schema.json", - "analytics": { - "segment": { - "key": "nYHwrLGCNSiWISNZYeXtFSNkGHHnrlWX" - } - }, - "name": "Starter Kit", - "logo": { - "dark": "/docs/logo/logo-esi-full-white.svg", - "light": "/docs/logo/logo-esi-full.svg" - }, - "favicon": "favicon.svg", - "layout": "topnav", - "sidebar": { - "items": "undecorated" - }, - "colors": { - "primary": "#7300E5", - "light": "#FFFFFF", - "dark": "#7300E5", - "anchors": { - "from": "#7300E5", - "to": "#7300f5" - }, - "background": { - "light": "#ffffff", - "dark": "#030712" - } - }, - "topbarLinks": [], - "topbarCtaButton": { - "name": "Back to your Organization", - "url": "https://app.externalsecrets.com", - "style": "roundedRectangle" - }, - "anchors": [], - "tabs":[ - { - "name": "Reloader", - "url": "docs/open_source/reloader" - }, - { - "name": "Audit", - "url": "docs/enterprise/audit" - }, - { - "name": "External Secrets Enterprise", - "url": "docs/enterprise/externalsecrets" - } - ], - "navigation": - [ - { "group": "Get Started", - "pages": [ - "docs/enterprise/audit/introduction", - "docs/enterprise/audit/installation" - ] - }, - { - "group": "Dashboard", - "pages": [ - "docs/enterprise/audit/dashboard/lineage", - "docs/enterprise/audit/dashboard/filters" - ] - }, - { - "group": "Destinations", - "pages": [ - "docs/enterprise/audit/destinations/quickstart" - ] - }, - { - "group": "Policies", - "pages": [ - "docs/enterprise/audit/policies/quickstart", - "docs/enterprise/audit/policies/policy-execution-types", - { - "group": "Examples", - "pages": [ - "docs/enterprise/audit/policies/examples/access-compliance", - "docs/enterprise/audit/policies/examples/cross-provider-duplication", - "docs/enterprise/audit/policies/examples/ca-verification", - "docs/enterprise/audit/policies/examples/password-compliance", - "docs/enterprise/audit/policies/examples/rotation-compliance" - ] - } - ] - }, - { - "group": "Listener", - "pages": [ - "docs/enterprise/audit/listener/introduction", - { - "group": "Providers", - "pages": [ - "docs/enterprise/audit/listener/providers/hashicorp-vault", - "docs/enterprise/audit/listener/providers/gcp-secret-manager", - "docs/enterprise/audit/listener/providers/aws-secrets-manager", - "docs/enterprise/audit/listener/providers/aws-parameter-store", - "docs/enterprise/audit/listener/providers/azure-key-vault" - ] - } - ] - }, - { - "group": "Aditional documentation", - "pages": [ - "docs/enterprise/audit/reference/listener-reference", - "docs/enterprise/audit/reference/policy-reference", - "docs/enterprise/audit/reference/troubleshooting" - ] - }, - { - "group": "ESI Agent", - "pages": [ - "docs/enterprise/externalsecrets/esi-agent/quickstart", - { - "group": "Guides", - "pages": [ - "docs/enterprise/externalsecrets/esi-agent/guides/namespaced-deployments", - "docs/enterprise/externalsecrets/esi-agent/guides/auto-updates" - ] - }, - { - "group": "Reference", - "pages": [ - "docs/enterprise/externalsecrets/esi-agent/reference/api-reference", - "docs/enterprise/externalsecrets/esi-agent/reference/architecture" - ] - }, - "docs/enterprise/externalsecrets/esi-agent/troubleshooting" - ] - }, - { - "group": "External Secrets Enterprise", - "pages": [ - "docs/enterprise/externalsecrets/quickstart", - "docs/enterprise/externalsecrets/dynamic-credentials", - { - "group": "Generators", - "pages": [ - "docs/enterprise/externalsecrets/generators/iam-keys", - "docs/enterprise/externalsecrets/generators/neo4j", - "docs/enterprise/externalsecrets/generators/postgresql" - ] - }, - { - "group": "Pod Webhook", - "pages": [ - "docs/enterprise/externalsecrets/pod-webhook/index", - "docs/enterprise/externalsecrets/pod-webhook/installation", - "docs/enterprise/externalsecrets/pod-webhook/annotations", - "docs/enterprise/externalsecrets/pod-webhook/usage-examples", - "docs/enterprise/externalsecrets/pod-webhook/troubleshooting" - ] - }, - { - "group": "ESI CLI", - "pages": [ - "docs/enterprise/externalsecrets/esi-cli/index", - "docs/enterprise/externalsecrets/esi-cli/modes", - "docs/enterprise/externalsecrets/esi-cli/flags", - "docs/enterprise/externalsecrets/esi-cli/injection-mechanisms", - "docs/enterprise/externalsecrets/esi-cli/federation", - "docs/enterprise/externalsecrets/esi-cli/usage-examples" - ] - }, - - { - "group": "Federation", - "pages": [ - "docs/enterprise/externalsecrets/federation/index", - "docs/enterprise/externalsecrets/federation/concepts", - "docs/enterprise/externalsecrets/federation/server-setup", - "docs/enterprise/externalsecrets/federation/client-setup", - "docs/enterprise/externalsecrets/federation/authn-authz", - "docs/enterprise/externalsecrets/federation/example" - ] - }, - { - "group": "Workflows", - "pages": [ - "docs/enterprise/externalsecrets/workflows/introduction", - "docs/enterprise/externalsecrets/workflows/concepts", - "docs/enterprise/externalsecrets/workflows/reference", - "docs/enterprise/externalsecrets/workflows/examples", - "docs/enterprise/externalsecrets/workflows/troubleshooting" - ] - } - ] - }, - { - "group": "Getting Started", - "pages": [ - "docs/open_source/reloader/introduction", - "docs/open_source/reloader/quickstart" - ]}, - { - "group": "Configuration", - "pages": [ - { - "group" : "Notification Sources", - "pages": [ - "docs/open_source/reloader/sources/gcp-pubsub-source", - "docs/open_source/reloader/sources/awssqs-source", - "docs/open_source/reloader/sources/vault-source", - "docs/open_source/reloader/sources/azure-eventgrid-source", - "docs/open_source/reloader/sources/webhook-source", - "docs/open_source/reloader/sources/kubernetes-secret-source" - ] - }, - { - "group": "Trigger Destinations", - "pages": [ - "docs/open_source/reloader/destinations/deployments", - "docs/open_source/reloader/destinations/external-secrets" - ] - } - ] - }, - { - "group": "Reference", - "pages": ["docs/open_source/reloader/reference/api-reference"] - } - ], - "footerSocials": { - "x": "https://x.com/XSecretsInc", - "github": "https://github.com/external-secrets-inc", - "linkedin": "https://www.linkedin.com/company/external-secrets-inc" - } -} From 950f4629ade7de8e0d7205ce28557687dff3da8a Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Fri, 25 Jul 2025 09:59:08 -0300 Subject: [PATCH 3/6] fix: tutorial Signed-off-by: Gustavo Carvalho --- .../externalsecrets/tutorials/workflows.mdx | 136 +++++++++--------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/docs/enterprise/externalsecrets/tutorials/workflows.mdx b/docs/enterprise/externalsecrets/tutorials/workflows.mdx index b1c866a..412f04b 100644 --- a/docs/enterprise/externalsecrets/tutorials/workflows.mdx +++ b/docs/enterprise/externalsecrets/tutorials/workflows.mdx @@ -25,57 +25,59 @@ This template has two input parameters: `secretName` and `storeName`, which make Save the following manifest as `workflow-template.yaml`: -{`apiVersion: workflows.external-secrets.io/v1alpha1 -kind: WorkflowTemplate -metadata: - name: generate-and-push-password -spec: - version: v1alpha1 - name: Generate and Push Password - parameterGroups: - - name: Destination - description: "Where to push the generated secret" - parameters: - - name: secretName - description: "Name of the secret to be created in the target store" - type: string - required: true - - name: storeName - description: "Name of the SecretStore to push the secret to" - type: secretstore - required: true - jobs: - generateAndPush: - standard: - steps: - - name: generatePassword - generator: - kind: Password - spec: - passwordSpec: - length: 32 - digits: 4 - symbols: 4 - outputs: - - name: password - type: string - sensitive: true - - name: pushToStore - push: - destination: - secretStoreRef: - name: "{{ .global.parameters.storeName }}" - data: - - secretKey: password - remoteRef: - key: "{{ .global.jobs.generateAndPush.generatePassword.password }}" - name: "{{ .global.parameters.secretName }}"`} +{` +--- + apiVersion: workflows.external-secrets.io/v1alpha1 + kind: WorkflowTemplate + metadata: + name: generate-and-push-password + spec: + version: v1alpha1 + name: Generate and Push Password + parameterGroups: + - name: Destination + description: "Where to push the generated secret" + parameters: + - name: secretName + description: "Name of the secret to be created in the target store" + type: string + required: true + - name: storeName + description: "Name of the SecretStore to push the secret to" + type: secretstore + required: true + jobs: + generateAndPush: + standard: + steps: + - name: generatePassword + generator: + kind: Password + spec: + passwordSpec: + length: 32 + digits: 4 + symbols: 4 + outputs: + - name: password + type: string + sensitive: true + - name: pushToStore + push: + destination: + secretStoreRef: + name: "{{ .global.parameters.storeName }}" + data: + - secretKey: password + remoteRef: + key: "{{ .global.jobs.generateAndPush.generatePassword.password }}" + name: "{{ .global.parameters.secretName }}"`} Apply it to your cluster: -{`kubectl apply -f workflow-template.yaml`} +kubectl apply -f workflow-template.yaml --- @@ -86,8 +88,8 @@ A `WorkflowRun` executes a `WorkflowTemplate` a single time. We'll use it to run Save the following manifest as `workflow-run.yaml`: - -{`apiVersion: workflows.external-secrets.io/v1alpha1 +```yaml +apiVersion: workflows.external-secrets.io/v1alpha1 kind: WorkflowRun metadata: name: run-password-generation @@ -96,20 +98,19 @@ spec: name: generate-and-push-password arguments: secretName: "my-app-password" - storeName: "aws-backend"`} - - + storeName: "aws-backend" +``` Apply it to trigger the workflow: - -{`kubectl apply -f workflow-run.yaml`} - +```bash +kubectl apply -f workflow-run.yaml +``` You can check the status of the run: - -{`kubectl get workflowrun run-password-generation -o wide`} - +```bash +kubectl get workflowrun run-password-generation -o wide +``` --- @@ -119,8 +120,8 @@ A `WorkflowRunTemplate` is used to run a workflow on a recurring schedule. Here, Save the following manifest as `scheduled-workflow.yaml`: - -{`apiVersion: workflows.external-secrets.io/v1alpha1 +```yaml +apiVersion: workflows.external-secrets.io/v1alpha1 kind: WorkflowRunTemplate metadata: name: scheduled-password-rotation @@ -133,17 +134,16 @@ spec: name: generate-and-push-password arguments: secretName: "my-rotated-password" - storeName: "gcp-backend"`} - - + storeName: "gcp-backend" +``` Apply it to create the schedule: - -{`kubectl apply -f scheduled-workflow.yaml`} - +```bash +kubectl apply -f scheduled-workflow.yaml +``` You can check the status and see the history of runs for the template: - -{`kubectl describe workflowruntemplate scheduled-password-rotation`} - \ No newline at end of file +```bash +kubectl describe workflowruntemplate scheduled-password-rotation +``` \ No newline at end of file From 6847c06607d30753417a9df3ff6f50b6ed958f53 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Fri, 25 Jul 2025 10:06:04 -0300 Subject: [PATCH 4/6] fix: add waitForReady Signed-off-by: Gustavo Carvalho --- docs/enterprise/externalsecrets/get-started.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/enterprise/externalsecrets/get-started.mdx b/docs/enterprise/externalsecrets/get-started.mdx index 797567a..ccddd83 100644 --- a/docs/enterprise/externalsecrets/get-started.mdx +++ b/docs/enterprise/externalsecrets/get-started.mdx @@ -39,8 +39,16 @@ helm install esi-bundle \ --namespace esi-bundle \ --create-namespace \ --set global.trialLicenseAccepted=true \ + --set global.waitForReady=true \ + --timeout 10m \ oci://us-central1-docker.pkg.dev/external-secrets-inc-registry/public/charts/esi-bundle ``` + +The Helm installation will wait until everything is up and running. +This can take up to 10 minutes due to image downloads. + +You can disable this behavior by setting `global.waitForReady=false`. + This command installs the `esi-bundle` chart and all its dependencies, including an ingress controller. From b718a112dcee5b22434a4be060a314ab27b99499 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Fri, 25 Jul 2025 10:57:26 -0300 Subject: [PATCH 5/6] fix: workflow tutorial Signed-off-by: Gustavo Carvalho --- .../externalsecrets/tutorials/workflows.mdx | 209 ++++++++++-------- 1 file changed, 121 insertions(+), 88 deletions(-) diff --git a/docs/enterprise/externalsecrets/tutorials/workflows.mdx b/docs/enterprise/externalsecrets/tutorials/workflows.mdx index 412f04b..209f84f 100644 --- a/docs/enterprise/externalsecrets/tutorials/workflows.mdx +++ b/docs/enterprise/externalsecrets/tutorials/workflows.mdx @@ -12,138 +12,171 @@ This tutorial will guide you through a complete workflow in External Secrets Ent Before you begin, you will need: - A Kubernetes cluster. - External Secrets Enterprise installed. -- Two `SecretStore` resources named `aws-backend` and `gcp-backend`. You can use any provider, but for this tutorial, we assume these stores exist. --- -## Step 1: Define a Reusable Workflow with `WorkflowTemplate` -A `WorkflowTemplate` is a reusable blueprint for a series of actions. Here, we'll define a template that generates a strong password and pushes it to a secret store. +This tutorial will guide you through creating a scheduled workflow that generates a password and distributes it to multiple secret stores. We will use the preset `generate-and-distribute` workflow template. -This template has two input parameters: `secretName` and `storeName`, which makes it flexible and reusable for different use cases. + + -Save the following manifest as `workflow-template.yaml`: +### Step 1: Create Secret Stores - -{` ---- - apiVersion: workflows.external-secrets.io/v1alpha1 - kind: WorkflowTemplate - metadata: - name: generate-and-push-password - spec: - version: v1alpha1 - name: Generate and Push Password - parameterGroups: - - name: Destination - description: "Where to push the generated secret" - parameters: - - name: secretName - description: "Name of the secret to be created in the target store" - type: string - required: true - - name: storeName - description: "Name of the SecretStore to push the secret to" - type: secretstore - required: true - jobs: - generateAndPush: - standard: - steps: - - name: generatePassword - generator: - kind: Password - spec: - passwordSpec: - length: 32 - digits: 4 - symbols: 4 - outputs: - - name: password - type: string - sensitive: true - - name: pushToStore - push: - destination: - secretStoreRef: - name: "{{ .global.parameters.storeName }}" - data: - - secretKey: password - remoteRef: - key: "{{ .global.jobs.generateAndPush.generatePassword.password }}" - name: "{{ .global.parameters.secretName }}"`} - +First, we need to create two `SecretStore` resources where the generated password will be stored. -Apply it to your cluster: +1. Navigate to the **Secret Stores** section in the External Secrets Enterprise UI. +2. Click on **Create Secret Store**. +3. Create the first `SecretStore` with the following details: + * **Name:** `fake` + * **Type:** `Fake` (This is useful for testing purposes) + * Add two data blocks: one with key `key-1` and value `duplicate`; the other one with name `key-2` and value `duplicate` as well. +4. Repeat the process to create a second `SecretStore`: + * **Name:** `fake2` + * **Type:** `Fake` - -kubectl apply -f workflow-template.yaml - +### Step 2: Create a Password Generator ---- +Next, we'll create a `Password` generator that will produce the secure passwords. + +1. Go to the **Generators** section in the UI. +2. Click on **Create Generator**. +3. Select **Password** as the generator type. +4. Configure the generator: + * **Name:** `my-password-generator` + * **Length:** `32` + * **Digits:** `4` + * **Symbols:** `4` +5. Save the generator. + +### Step 3: Create a Scheduled Workflow + +Now, let's create a `WorkflowRunTemplate` to schedule the password generation and distribution. + +1. Navigate to the **Workflows Templates** section. A list of Preset Workflow Templates will appear. +2. Find the `generate-and-distribute` template. Click the **Add Run Templates** button. +3. Fill in the parameters: + * **Name:** `my-scheduled-password` + * **Generator:** Select `my-password-generator`. + * **Stores to Distribute:** Add `fake` and `fake2` to the list. + * **Key to Distribute:** Type `generated-password`. This is the key that will be used to store the generated password in the stores. + * **Run Policy** select **Scheduled** + * **Schedule:** Select `Every` + * **Every** type `1m`. +4. External Secrets will Run this workflow every 1 minute, generating a new Password and +adding it to `fake` and `fake2` stores, under the `generated-password` key. +5. Click **Create** to save the `WorkflowRunTemplate`. -## Step 2: Run the Workflow Once with `WorkflowRun` +### Step 4: Check Runs +After creating your run template, you'll be able to see all the runs executing for that job. +Click on a Run to obtain information about all of the steps, its status and its execution time. -A `WorkflowRun` executes a `WorkflowTemplate` a single time. We'll use it to run our password generation template, providing the specific `secretName` and `storeName` as arguments. + + -Save the following manifest as `workflow-run.yaml`: +### Step 1: Create Secret Stores + +Create a file named `secret-stores.yaml` with the following content to define two `Fake` `SecretStore` resources. ```yaml -apiVersion: workflows.external-secrets.io/v1alpha1 -kind: WorkflowRun +apiVersion: external-secrets.io/v1beta1 +kind: SecretStore +metadata: + name: fake + namespace: eso-server +spec: + provider: + fake: + data: + - key: key-1 + value: duplicate + - key: key-2 + value: duplicate + +--- +apiVersion: external-secrets.io/v1beta1 +kind: SecretStore metadata: - name: run-password-generation + name: fake2 + namespace: eso-server spec: - templateRef: - name: generate-and-push-password - arguments: - secretName: "my-app-password" - storeName: "aws-backend" + provider: + fake: + data: + - key: key-3 + value: duplicate + - key: key-4 + value: duplicate ``` -Apply it to trigger the workflow: + +Apply the manifest to your cluster: ```bash -kubectl apply -f workflow-run.yaml +kubectl apply -f secret-stores.yaml ``` -You can check the status of the run: +### Step 2: Create a Password Generator -```bash -kubectl get workflowrun run-password-generation -o wide +Create a file named `password-generator.yaml` to define the `Password` generator. + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: Password +metadata: + name: my-password-generator + namespace: eso-server +spec: + length: 32 + digits: 4 + symbols: 4 ``` ---- +Apply it to your cluster: -## Step 3: Schedule the Workflow with `WorkflowRunTemplate` +```bash +kubectl apply -f password-generator.yaml +``` -A `WorkflowRunTemplate` is used to run a workflow on a recurring schedule. Here, we'll schedule our password generation workflow to run every 12 hours, pushing a new password to our `gcp-backend` store. +### Step 3: Create a Scheduled Workflow -Save the following manifest as `scheduled-workflow.yaml`: +Finally, create a `WorkflowRunTemplate` in a file named `scheduled-workflow.yaml`. This will run the `generate-and-distribute` workflow every 12 hours. ```yaml apiVersion: workflows.external-secrets.io/v1alpha1 kind: WorkflowRunTemplate metadata: - name: scheduled-password-rotation + name: my-scheduled-password + namespace: eso-server spec: runPolicy: scheduled: - cron: "0 */12 * * *" + every: "1m" runSpec: templateRef: - name: generate-and-push-password + name: generate-and-distribute arguments: - secretName: "my-rotated-password" - storeName: "gcp-backend" + generator: + kind: Password + name: my-password-generator + storesToDistribute: + - name: fake + kind: SecretStore + - name: fake2 + kind: SecretStore + keyToDistribute: generated-password ``` -Apply it to create the schedule: + +Apply the manifest: ```bash kubectl apply -f scheduled-workflow.yaml ``` -You can check the status and see the history of runs for the template: +You can check the status and history of the scheduled workflow runs: ```bash -kubectl describe workflowruntemplate scheduled-password-rotation -``` \ No newline at end of file +kubectl get workflowruns -n eso-server +``` + + + From 13bbd52bfcfab8ff1a65e794c653bee6c5b3fa97 Mon Sep 17 00:00:00 2001 From: Gustavo Carvalho Date: Fri, 25 Jul 2025 13:11:35 -0300 Subject: [PATCH 6/6] fix: remaining fixes Signed-off-by: Gustavo Carvalho --- .../externalsecrets/tutorials/workflows.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/enterprise/externalsecrets/tutorials/workflows.mdx b/docs/enterprise/externalsecrets/tutorials/workflows.mdx index 209f84f..30c87b2 100644 --- a/docs/enterprise/externalsecrets/tutorials/workflows.mdx +++ b/docs/enterprise/externalsecrets/tutorials/workflows.mdx @@ -1,5 +1,5 @@ --- -title: 'Workflow Tutorial' +title: 'Workflows' description: 'A step-by-step guide to using External Secrets Enterprise Workflows.' --- @@ -26,14 +26,14 @@ This tutorial will guide you through creating a scheduled workflow that generate First, we need to create two `SecretStore` resources where the generated password will be stored. 1. Navigate to the **Secret Stores** section in the External Secrets Enterprise UI. -2. Click on **Create Secret Store**. +2. Click on **Add Secret Store**. 3. Create the first `SecretStore` with the following details: * **Name:** `fake` - * **Type:** `Fake` (This is useful for testing purposes) + * **Provider:** `Fake` (This is useful for testing purposes) * Add two data blocks: one with key `key-1` and value `duplicate`; the other one with name `key-2` and value `duplicate` as well. 4. Repeat the process to create a second `SecretStore`: * **Name:** `fake2` - * **Type:** `Fake` + * **Provider:** `Fake` ### Step 2: Create a Password Generator @@ -41,11 +41,11 @@ Next, we'll create a `Password` generator that will produce the secure passwords 1. Go to the **Generators** section in the UI. 2. Click on **Create Generator**. -3. Select **Password** as the generator type. +3. Select **Passwords** as the generator type. 4. Configure the generator: * **Name:** `my-password-generator` - * **Length:** `32` * **Digits:** `4` + * **Length:** `32` * **Symbols:** `4` 5. Save the generator. @@ -54,15 +54,15 @@ Next, we'll create a `Password` generator that will produce the secure passwords Now, let's create a `WorkflowRunTemplate` to schedule the password generation and distribution. 1. Navigate to the **Workflows Templates** section. A list of Preset Workflow Templates will appear. -2. Find the `generate-and-distribute` template. Click the **Add Run Templates** button. +2. Find the `generate-and-distribute-workflow` template. Click the **Add Run Templates** button. 3. Fill in the parameters: * **Name:** `my-scheduled-password` * **Generator:** Select `my-password-generator`. * **Stores to Distribute:** Add `fake` and `fake2` to the list. * **Key to Distribute:** Type `generated-password`. This is the key that will be used to store the generated password in the stores. - * **Run Policy** select **Scheduled** - * **Schedule:** Select `Every` - * **Every** type `1m`. + * **Run Policy** select **Scheduled Interval** + * **Schedule:** Select `Every time period` + * **Every time period** type `1m`. 4. External Secrets will Run this workflow every 1 minute, generating a new Password and adding it to `fake` and `fake2` stores, under the `generated-password` key. 5. Click **Create** to save the `WorkflowRunTemplate`.