external-secrets/design/008-pushsecret-update-policy.md

---
title: PushSecret Update Policy
version: v1alpha1
authors: Moritz Johner
creation-date: 2023-08-25
status: draft
---

PushSecret Update Policy

Table of Contents

// autogen please

Summary

The PushSecret update procedure needs to be configurable so users can control its behaviour.

Motivation

The motivation is to enhance the configurability of the PushSecret lifecycle within the External Secrets Operator (ESO). Currently, there is a need for users to have more control over the behavior of PushSecret when updating values at the secret provider.

The use-case for updatePolicy is the following: Users would like to use ESO generate a password and store it in an external store. Once the password is generated and pushed, they want the secret store to become the source of truth, so that the password won't be overridden when ExternalSecret or Secret Resources are deleted and/or regenerated.

More context in #2643.

Context

When ESO intends to push a secret to the provider, several cases need to be considered for managing the lifecycle:

1. Ownership of Pre-existing Secret: Should ESO take ownership over a pre-existing secret?
2. Overwriting Existing Value: Should ESO overwrite an existing value?
3. Merging Values: Should ESO merge structured data?

This design document concerns the second point.

The PushSecret lifecycle consists of these 3 parts:

• create the secret on the provider side
• update the secret value every spec.refreshInterval
• delete the secret

For each part we can apply a policy. For this design document the update part is relevant. The following flowchart illustrates the decision-making process:

flowchart TD

    C{Create} --> |no policy here| F{Update}
    F -->|updatePolicy=Replace| G[Always overrides the existing value]
    F -->|updatePolicy=IfNotExists| H[Writes the value only\n if no value exists]
    G --> F
    H --> F
    G --> I{Delete}
    H --> I{Delete}
    I --> |deletionPolicy=Delete| J[Deletes the secret]
    I --> |deletionPolicy=None| K[Retains the existing secret]

Proposal

The proposed solution is to introduce an updatePolicy field within the PushSecret specification. This field allows users to configure the behavior of updates during the PushSecret lifecycle.

By default, the value of updatePolicy is set to Replace, meaning that the existing value will always be overridden. Alternatively, users can set the value to IfNotExists, which prevents a write operation if a value already exists.

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: pushsecret-example
  namespace: default
spec:
  updatePolicy: Replace # Replace (default) or IfNotExists
  # ...

For the future we can consider adding more policies like Merge of needed.

Consequences

• Enhanced Flexibility: Users gain more control over how updates are managed within the PushSecret lifecycle, providing greater customization.
• Reduced Risk of Data Loss: With clearer control over updates, the risk of unintended value overwrites or deletions is minimized.
• Complexity for Users: Users need to understand the implications of different updatePolicy settings to use the feature effectively.
• Improved Value Management: The feature aligns with the goal of efficiently managing secret values within Kubernetes environments.

Acceptance Criteria

• implementation for all core providers (+issues tracking progress)
  • return not implemented error if specified but not implemented
  • ensure there is a fallback for an empty updatePolicy (for migration purposes)
• observability: a Status SecretAlreadyExists (as a pair of SecretSynced, SecretDeleted ) to indicate it.
• tests: controller tests for this new field should be sufficient
• the API changes need to be documented
  • API/CRD spec inline documentation
  • PushSecret API documentation
  • Guides section for PushSecret + updatePolicy
    • We need to be verbose on specifying that the use of updatePolicy breaks idempotency contracts, and that it should be used with care by the user.