Skip to content

OSDOCS-17704 updated create-only mode #104178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ShaunaDiaz merged 1 commit into from
Jan 13, 2026
+37 −40
Merged

OSDOCS-17704 updated create-only mode #104178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions modules/zero-trust-manager-pause-reconciliation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,15 @@

:_mod-docs-content-type: PROCEDURE
[id="zero-trust-manager-pause-reconciliation_{context}"]
= Pausing Operator reconciliation

= Pausing Operator reconciliation by annotation
[role="_abstract"]
Pause reconciliation of the operands by enabling `create-only` mode. This setting prevents the Operator from automatically reverting your manual changes to the desired state. You can enable this mode by updating the Operator's subscription object.

Reconciliation by annotation supports the `SpireServer`, `SpireAgent`, `SpiffeCSIDriver`, `SpireOIDCDiscoveryProvider`, and the `ZeroTrustWorkloadIdentityManager` custom resources. You can pause the reconciliation process by adding an annotation.
[IMPORTANT]
====
When `create-only` mode is disabled, the Operator overwrites the resources if any conflicts exist.
====

.Prerequisites

Expand All @@ -17,11 +22,11 @@ Reconciliation by annotation supports the `SpireServer`, `SpireAgent`, `SpiffeCS

.Procedure

* To pause reconciling the `SpireServer` custom resource, add the `create-only` annotation to the named `cluster` by running the following command:
* To pause reconciling the operands resources managed by the Operator, add the environment variable `CREATE_ONLY_MODE`: `true` in the subscription object by running the following command:
+
[source,terminal]
----
$ oc annotate SpireServer cluster -n zero-trust-workload-identity-manager ztwim.openshift.io/create-only=true
$ oc -n $OPERATOR_NAMESPACE patch subscription openshift-zero-trust-workload-identity-manager --type='merge' -p '{"spec":{"config":{"env":[{"name":"CREATE_ONLY_MODE","value":"true"}]}}}'
Copy link
Member

@lunarwhite lunarwhite Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enhancement: Accept case-insensitive "TRUE"/"FALSE" for CREATE_ONLY_MODE env var using strings.EqualFold(). Any random/invalid value will default to false (disabled) for safety.

CREATE_ONLY_MODE env var handling

• Accepts: true/True/TRUE → Enables create-only mode • Accepts: false/False/FALSE → Disables create-only mode • Any other value (yes, 1, random, etc.) → Defaults to DISABLED

The check is case-insensitive. Recommend documenting "true" or "false" as accepted values.

@sayak-redhat Why putting these bits here? This PR is part of the 1.0.0 GA version only, obviously openshift/zero-trust-workload-identity-manager#89 hasn't merged && no release created yet. Have you mixed up the versioning which I told you early

Copy link

@sayak-redhat sayak-redhat Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry @lunarwhite i misplaced with the github prs

----

.Verification
Expand All @@ -32,15 +37,30 @@ $ oc annotate SpireServer cluster -n zero-trust-workload-identity-manager ztwim.
$ oc get SpireServer cluster -o yaml
----

.Example output
The following is an example that confirms that the 'create-only' mode is active.
Copy link
Contributor

@ShaunaDiaz ShaunaDiaz Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following is an example that confirms that the 'create-only' mode is active.
+
The following is an example that confirms that the 'create-only' mode is active.

this is not indented properly (see the preview)

[source,yaml]
----
status:
conditions:
- lastTransitionTime: "2025-09-03T12:13:39Z"
message: Create-only mode is enabled via ztwim.openshift.io/create-only annotation
- lastTransitionTime: "2025-12-23T11:36:58Z"
message: All components are ready
reason: Ready
status: "True"
type: Ready
- lastTransitionTime: "2025-12-23T11:36:58Z"
message: All operand CRs are ready
reason: Ready
status: "True"
type: OperandsAvailable
- lastTransitionTime: "2025-12-23T11:36:58Z"
message: create-only mode enabled
reason: CreateOnlyModeEnabled
status: "True"
type: CreateOnlyMode
Copy link

@anirudhAgniRedhat anirudhAgniRedhat Dec 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.Verification

  • Check the status of the ZeroTrustWorkloadIdentityManager resource to confirm that the create-only mode is active. The status must be true and the reason must be CreateOnlyModeEnabled.

$ oc get zerotrustworkloadidentitymanager cluster -o yaml

.Example output

status:
  conditions:
  - lastTransitionTime: "2025-12-23T11:36:58Z"
    message: All components are ready
    reason: Ready
    status: "True"
    type: Ready
  - lastTransitionTime: "2025-12-23T11:36:58Z"
    message: All operand CRs are ready
    reason: Ready
    status: "True"
    type: OperandsAvailable
  - lastTransitionTime: "2025-12-23T11:36:58Z"
    message: create-only mode enabled
    reason: CreateOnlyModeEnabled
    status: "True"
    type: CreateOnlyMode

Copy link
Contributor Author

@wgabor0427 wgabor0427 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

----

[IMPORTANT]
====
The Operator updates the upgradeable condition to `false` in the `operatorCondition` resource. You might not be able to upgrade the Operator when in `create-only` mode.
====

38 changes: 6 additions & 32 deletions modules/zero-trust-manager-restart-reconciliation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,44 +5,18 @@
:_mod-docs-content-type: PROCEDURE
[id="zero-trust-manager-restart-reconciliation_{context}"]

= Resuming Operator reconciliation by annotation
= Resuming Operator reconciliation

.Procedure

Follow these steps to restart the reconciliation process:

. Run the `oc annotate` command, adding a hyphen (`-`) at the end of the annotation name. This removes the annotation from the cluster resource.
+
[source,terminal]
----
$ oc annotate SpireServer cluster -n zero-trust-workload-identity-manager ztwim.openshift.io/create-only-
----
[role="_abstract"]
To pause Operator reconciliation for manual configuration or debugging, enable the `create-only`` mode. This prevents the controller from overwriting your changes. You can enable this mode by setting the environment variable in the subscription object.

. Restart the controller by running the following command:
+
[source,terminal]
----
$ oc rollout restart deploy/zero-trust-workload-identity-manager-controller-manager -n zero-trust-workload-identity-manager
----
.Procedure

.Verification
* Check the status of the `SpireServer` resource to confirm that the `create-only` mode is disabled. The `status` must be `false` and the `reason` must be `CreateOnlyModeDisabled`.
* To restart reconciling the Operator-managed resources, add the environment variable `CREATE_ONLY_MODE`: `false` in the subscription object by running the following command:
+
[source,terminal]
----
$ oc get SpireServer cluster -o yaml
$ oc -n $OPERATOR_NAMESPACE patch subscription openshift-zero-trust-workload-identity-manager --type='merge' -p '{"spec":{"config":{"env":[{"name":"CREATE_ONLY_MODE","value":"false"}]}}}'
----

.Example output
[source,yaml]
----
status:
conditions:
- lastTransitionTime: "2025-09-03T12:13:39Z"
message: Create-only mode is enabled via ztwim.openshift.io/create-only annotation
reason: CreateOnlyModeDisabled
status: "False"
type: CreateOnlyMode
----

Once `create-only` mode is enabled, it persists until the Operator pod restarts, even if the annotation is removed. To exit this mode, you might need to remove or unset the annotation and restart the Operator pod.
5 changes: 4 additions & 1 deletion ...ity/zero_trust_workload_identity_manager/zero-trust-manager-reconciliation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@ include::_attributes/common-attributes.adoc[]

toc::[]

By enabling the `create-only` mode, you can pause the Operator reconciliation, which allows you to perform manual configurations or debug without the controller overwriting your changes. This is done by annotating the API resources which are managed by the Operator. The following scenarios are examples of when the `create-only` mode might be of use:
[role="_abstract"]
To pause Operator reconciliation, enable `create-only` mode by setting an environment variable in the subscription object. By setting this value, you can perform manual configurations or debug the operator without the controller overwriting your changes.

The following scenarios are examples of when the `create-only` mode might be of use:

**Manual Customization Required**: You need to customize operator-managed resources (ConfigMaps, Deployments, DaemonSets, etc.) with specific configurations that differ from the operator's defaults

Expand Down