diff --git a/Makefile b/Makefile index ae08d7c9a..c331315b3 100644 --- a/Makefile +++ b/Makefile @@ -736,6 +736,7 @@ docs/about/04_coherence_spec.adoc: $(API_GO_FILES) utils/docgen/main.go api/v1/coherenceresourcespec_types.go \ api/v1/coherence_types.go \ api/v1/coherenceresource_types.go \ + api/v1/coherencejobresource_types.go \ > docs/about/04_coherence_spec.adoc # ---------------------------------------------------------------------------------------------------------------------- diff --git a/api/v1/coherencejobresource_types.go b/api/v1/coherencejobresource_types.go index 1f39b96cc..1f595255b 100644 --- a/api/v1/coherencejobresource_types.go +++ b/api/v1/coherencejobresource_types.go @@ -18,7 +18,7 @@ import ( // ----- Coherence type ------------------------------------------------------------------ -// CoherenceJob is the top level schema for the Coherence API and custom resource definition (CRD) +// CoherenceJob is the top level schema for the CoherenceJob API and custom resource definition (CRD) // for configuring Coherence Job workloads. // // +kubebuilder:object:root=true diff --git a/api/v1/coherenceresourcespec_types.go b/api/v1/coherenceresourcespec_types.go index edf815d7a..32a27362e 100644 --- a/api/v1/coherenceresourcespec_types.go +++ b/api/v1/coherenceresourcespec_types.go @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 2024, Oracle and/or its affiliates. + * Copyright (c) 2020, 2025, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ @@ -286,6 +286,10 @@ type CoherenceResourceSpec struct { // The default labels to use are determined by the Operator. // +optional SiteLabel *string `json:"siteLabel,omitempty"` + // Lifecycle applies actions that the management system should take in response to container lifecycle events. + // Cannot be updated. + // +optional + Lifecycle *corev1.Lifecycle `json:"lifecycle,omitempty"` } // Action is an action to execute when the StatefulSet becomes ready. @@ -877,6 +881,8 @@ func (in *CoherenceResourceSpec) CreateCoherenceContainer(deployment CoherenceRe in.StartupProbe.UpdateProbeSpec(healthPort, DefaultLivenessPath, c.StartupProbe) } + c.Lifecycle = in.Lifecycle + return c } diff --git a/api/v1/create_job_test.go b/api/v1/create_job_test.go index bd2e1e42f..40ff19edc 100644 --- a/api/v1/create_job_test.go +++ b/api/v1/create_job_test.go @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 2024, Oracle and/or its affiliates. + * Copyright (c) 2020, 2025, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ @@ -9,6 +9,7 @@ package v1_test import ( coh "github.com/oracle/coherence-operator/api/v1" corev1 "k8s.io/api/core/v1" + "k8s.io/apimachinery/pkg/util/intstr" "k8s.io/utils/ptr" "testing" ) @@ -136,3 +137,35 @@ func TestCreateJobWithEnvVarsFrom(t *testing.T) { // assert that the StatefulSet is as expected assertJobCreation(t, deployment, expected) } + +func TestAddLifecycleToJobCoherenceContainer(t *testing.T) { + lc := &corev1.Lifecycle{ + PostStart: &corev1.LifecycleHandler{ + HTTPGet: &corev1.HTTPGetAction{ + Path: "/foo", + Port: intstr.FromInt32(1234), + }, + }, + PreStop: &corev1.LifecycleHandler{ + HTTPGet: &corev1.HTTPGetAction{ + Path: "/bar", + Port: intstr.FromInt32(987), + }, + }, + } + + spec := coh.CoherenceJobResourceSpec{ + CoherenceResourceSpec: coh.CoherenceResourceSpec{ + Lifecycle: lc, + }, + } + + // Create the test deployment + deployment := createTestCoherenceJobDeployment(spec) + // Create expected StatefulSet + expected := createMinimalExpectedJob(deployment) + expected.Spec.Template.Spec.Containers[0].Lifecycle = lc + + // assert that the StatefulSet is as expected + assertJobCreation(t, deployment, expected) +} diff --git a/api/v1/create_statefulset_test.go b/api/v1/create_statefulset_test.go index 23f856959..d5740618c 100644 --- a/api/v1/create_statefulset_test.go +++ b/api/v1/create_statefulset_test.go @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 2024, Oracle and/or its affiliates. + * Copyright (c) 2020, 2025, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ @@ -748,3 +748,33 @@ func TestCreateStatefulSetWithGlobalAnnotations(t *testing.T) { // assert that the Job is as expected assertStatefulSetCreation(t, deployment, stsExpected) } + +func TestAddLifecycleToStatefulSetCoherenceContainer(t *testing.T) { + lc := &corev1.Lifecycle{ + PostStart: &corev1.LifecycleHandler{ + HTTPGet: &corev1.HTTPGetAction{ + Path: "/foo", + Port: intstr.FromInt32(1234), + }, + }, + PreStop: &corev1.LifecycleHandler{ + HTTPGet: &corev1.HTTPGetAction{ + Path: "/bar", + Port: intstr.FromInt32(987), + }, + }, + } + + spec := coh.CoherenceResourceSpec{ + Lifecycle: lc, + } + + // Create the test deployment + deployment := createTestDeployment(spec) + // Create expected StatefulSet + stsExpected := createMinimalExpectedStatefulSet(deployment) + stsExpected.Spec.Template.Spec.Containers[0].Lifecycle = lc + + // assert that the StatefulSet is as expected + assertStatefulSetCreation(t, deployment, stsExpected) +} diff --git a/docs/about/04_coherence_spec.adoc b/docs/about/04_coherence_spec.adoc index 955b03b7d..882b05cbc 100644 --- a/docs/about/04_coherence_spec.adoc +++ b/docs/about/04_coherence_spec.adoc @@ -24,13 +24,49 @@ These are all the types and fields that are used in the Coherence CRD. TIP: This document was generated from comments in the Go structs in the pkg/api/ directory. +=== Coherence + +Coherence is the top level schema for the Coherence API and custom resource definition (CRD). + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| metadata |   m| https://{k8s-doc-link}/#objectmeta-v1-meta[metav1.ObjectMeta] | false +m| spec |   m| <> | false +m| status |   m| <> | false +|=== + + +=== CoherenceJob + +CoherenceJob is the top level schema for the CoherenceJob API and custom resource definition (CRD) for configuring Coherence Job workloads. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| metadata |   m| https://{k8s-doc-link}/#objectmeta-v1-meta[metav1.ObjectMeta] | false +m| spec |   m| <> | false +m| status |   m| <> | false +|=== + + === Table of Contents * <> * <> -* <> * <> * <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> * <> +* <> * <> * <> * <> @@ -62,10 +98,6 @@ TIP: This document was generated from comments in the Go structs in the pkg/api/ * <> * <> * <> -* <> -* <> -* <> -* <> === Action @@ -95,6 +127,145 @@ m| annotations | Annotations to add to the Job. m| map[string]string | false <> +=== ApplicationSpec + +ApplicationSpec is the specification of the application deployed into the Coherence. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| type | The application type to execute. This field would be set if using the Coherence Graal image and running a none-Java application. For example if the application was a Node application this field would be set to "node". The default is to run a plain Java application. m| *string | false +m| main | Class is the Coherence container main class. The default value is com.tangosol.net.DefaultCacheServer. If the application type is non-Java this would be the name of the corresponding language specific runnable, for example if the application type is "node" the main may be a Javascript file. m| *string | false +m| args | Args is the optional arguments to pass to the main class. m| []string | false +m| workingDir | The application folder in the custom artifacts Docker image containing application artifacts. This will effectively become the working directory of the Coherence container. If not set the application directory default value is "/app". m| *string | false +m| cloudNativeBuildPack | Optional settings that may be configured if using a Cloud Native Buildpack Image. For example an image build with the Spring Boot Maven/Gradle plugin. See: https://github.com/paketo-buildpacks/spring-boot and https://buildpacks.io/ m| *<> | false +m| springBootFatJar | SpringBootFatJar is the full path name to the Spring Boot fat jar if the application image has been built by just adding a Spring Boot fat jar to the image. If this field is set then the application will be run by executing this jar. For example, if this field is "/app/libs/foo.jar" the command line will be "java -jar app/libs/foo.jar" m| *string | false +|=== + +<
> + +=== CloudNativeBuildPackSpec + +CloudNativeBuildPackSpec is the configuration when using a Cloud Native Buildpack Image. For example an image build with the Spring Boot Maven/Gradle plugin. See: https://github.com/paketo-buildpacks/spring-boot and https://buildpacks.io/ + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| enabled | Enable or disable buildpack detection. The operator will automatically detect Cloud Native Buildpack images but if this auto-detection fails to work correctly for a specific image then this field can be set to true to signify that the image is a buildpack image or false to signify that it is not a buildpack image. m| *bool | false +m| launcher |   m| *string | false +|=== + +<
> + +=== CoherenceJobList + +CoherenceJobList is a list of CoherenceJob resources. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| metadata |   m| https://{k8s-doc-link}/#listmeta-v1-meta[metav1.ListMeta] | false +m| items |   m| []<> | true +|=== + +<
> + +=== CoherenceJobProbe + + + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| readyCount | The number of job Pods that should be ready before executing the Probe. If not set the default will be the same as the job's Completions value. The probe will be executed on all Pods m| *int32 | false +|=== + +<
> + +=== CoherenceJobProbeStatus + + + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| pod |   m| string | false +m| lastReadyTime |   m| *https://{k8s-doc-link}/#time-v1-meta[metav1.Time] | false +m| lastProbeTime |   m| *https://{k8s-doc-link}/#time-v1-meta[metav1.Time] | false +m| success |   m| *bool | false +m| error |   m| *string | false +|=== + +<
> + +=== CoherenceJobResourceSpec + +CoherenceJobResourceSpec defines the specification of a CoherenceJob resource. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| cluster | The name of the Coherence cluster that this CoherenceJob resource belongs to. A CoherenceJob will typically be part of an existing cluster, so this field is required. m| string | false +m| completions | Specifies the desired number of successfully finished pods the job should be run with. Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value. Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ m| *int32 | false +m| syncCompletionsToReplicas | SyncCompletions is a flag to indicate that the Operator should always set the Completions value to be the same as the Replicas value. When a Job is then scaled, the Completions value will also be changed. m| *bool | false +m| podFailurePolicy | Specifies the policy of handling failed pods. In particular, it allows to specify the set of actions and conditions which need to be satisfied to take the associated action. If empty, the default behaviour applies - the counter of failed pods, represented by the job's .status.failed field, is incremented, and it is checked against the backoffLimit. This field cannot be used in combination with restartPolicy=OnFailure. + + + +This field is alpha-level. To use this field, you must enable the `JobPodFailurePolicy` feature gate (disabled by default). m| *https://{k8s-doc-link}/#podfailurepolicy-v1-batch[batchv1.PodFailurePolicy] | false +m| backoffLimit | Specifies the number of retries before marking this job failed. Defaults to 6 m| *int32 | false +m| ttlSecondsAfterFinished | ttlSecondsAfterFinished limits the lifetime of a Job that has finished execution (either Complete or Failed). If this field is set, ttlSecondsAfterFinished after the Job finishes, it is eligible to be automatically deleted. When the Job is being deleted, its lifecycle guarantees (e.g. finalizers) will be honored. If this field is unset, the Job won't be automatically deleted. If this field is set to zero, the Job becomes eligible to be deleted immediately after it finishes. m| *int32 | false +m| completionMode | CompletionMode specifies how Pod completions are tracked. It can be `NonIndexed` (default) or `Indexed`. + + + +`NonIndexed` means that the Job is considered complete when there have been .spec.completions successfully completed Pods. Each Pod completion is homologous to each other. + + + +`Indexed` means that the Pods of a Job get an associated completion index from 0 to (.spec.completions - 1), available in the annotation batch.kubernetes.io/job-completion-index. The Job is considered complete when there is one successfully completed Pod for each index. When value is `Indexed`, .spec.completions must be specified and `.spec.parallelism` must be less than or equal to 10^5. In addition, The Pod name takes the form `$(job-name)-$(index)-$(random-string)`, the Pod hostname takes the form `$(job-name)-$(index)`. + + + +More completion modes can be added in the future. If the Job controller observes a mode that it doesn't recognize, which is possible during upgrades due to version skew, the controller skips updates for the Job. m| *https://{k8s-doc-link}/#completionmode-v1-batch[batchv1.CompletionMode] | false +m| suspend | Suspend specifies whether the Job controller should create Pods or not. If a Job is created with suspend set to true, no Pods are created by the Job controller. If a Job is suspended after creation (i.e. the flag goes from false to true), the Job controller will delete all active Pods associated with this Job. Users must design their workload to gracefully handle this. Suspending a Job will reset the StartTime field of the Job, effectively resetting the ActiveDeadlineSeconds timer too. Defaults to false. m| *bool | false +m| jobAnnotations | JobAnnotations are free-form yaml that will be added to the Coherence workload's `Job` as annotations. Any annotations should be placed BELOW this "annotations:" key, for example: + + + +The default behaviour is to copy all annotations from the `Coherence` resource to the `Job`, specifying any annotations in the `JobAnnotations` will override this behaviour and only include the `JobAnnotations`. + + + +annotations: + + foo.io/one: "value1" + + + foo.io/two: "value2" + + + + +see: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[Kubernetes Annotations] m| map[string]string | false +m| readyAction | ReadyAction is a probe that will be executed when one or more Pods reach the ready state. The probe will be executed on every Pod that is ready. One the required number of ready Pods is reached the probe will also be executed on every Pod that becomes ready after that time. m| *<> | false +m| forceExit | ForceExit is a flag to indicate whether the Operator should call System.exit to forcefully exit the process when the configured main class completes execution. m| *bool | false +m| envFrom | List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. m| []https://{k8s-doc-link}/#envfromsource-v1-core[corev1.EnvFromSource] | false +m| global | Global contains attributes that will be applied to all resources managed by the Coherence Operator. m| *<> | false +m| initResources | InitResources is the optional resource requests and limits for the init-container that the Operator adds to the Pod. + + ref: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + +The Coherence operator does not apply any default resources. m| *https://{k8s-doc-link}/#resourcerequirements-v1-core[corev1.ResourceRequirements] | false +|=== + +<
> + +=== CoherenceJobStatus + + + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| probeStatus |   m| []<> | false +|=== + +<
> + +=== CoherenceList + +CoherenceList is a list of Coherence resources. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| metadata |   m| https://{k8s-doc-link}/#listmeta-v1-meta[metav1.ListMeta] | false +m| items |   m| []<> | true +|=== + +<
> + === CoherenceResourceSpec CoherenceResourceSpec defines the specification of a Coherence resource. A Coherence resource is typically one or more Pods that perform the same functionality, for example storage members. @@ -175,36 +346,35 @@ m| schedulerName | If specified, the pod will be dispatched by specified schedul m| topologySpreadConstraints | TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. m| []https://{k8s-doc-link}/#topologyspreadconstraint-v1-core[corev1.TopologySpreadConstraint] | false m| rackLabel | RackLabel is an optional Node label to use for the value of the Coherence member's rack name. The default labels to use are determined by the Operator. m| *string | false m| siteLabel | SiteLabel is an optional Node label to use for the value of the Coherence member's site name The default labels to use are determined by the Operator. m| *string | false +m| lifecycle | Lifecycle applies actions that the management system should take in response to container lifecycle events. Cannot be updated. m| *https://{k8s-doc-link}/#lifecycle-v1-core[corev1.Lifecycle] | false |=== <
> -=== ApplicationSpec - -ApplicationSpec is the specification of the application deployed into the Coherence. - -[cols="1,10,1,1"options="header"] -|=== -| Field | Description | Type | Required -m| type | The application type to execute. This field would be set if using the Coherence Graal image and running a none-Java application. For example if the application was a Node application this field would be set to "node". The default is to run a plain Java application. m| *string | false -m| main | Class is the Coherence container main class. The default value is com.tangosol.net.DefaultCacheServer. If the application type is non-Java this would be the name of the corresponding language specific runnable, for example if the application type is "node" the main may be a Javascript file. m| *string | false -m| args | Args is the optional arguments to pass to the main class. m| []string | false -m| workingDir | The application folder in the custom artifacts Docker image containing application artifacts. This will effectively become the working directory of the Coherence container. If not set the application directory default value is "/app". m| *string | false -m| cloudNativeBuildPack | Optional settings that may be configured if using a Cloud Native Buildpack Image. For example an image build with the Spring Boot Maven/Gradle plugin. See: https://github.com/paketo-buildpacks/spring-boot and https://buildpacks.io/ m| *<> | false -m| springBootFatJar | SpringBootFatJar is the full path name to the Spring Boot fat jar if the application image has been built by just adding a Spring Boot fat jar to the image. If this field is set then the application will be run by executing this jar. For example, if this field is "/app/libs/foo.jar" the command line will be "java -jar app/libs/foo.jar" m| *string | false -|=== - -<
> - -=== CloudNativeBuildPackSpec +=== CoherenceResourceStatus -CloudNativeBuildPackSpec is the configuration when using a Cloud Native Buildpack Image. For example an image build with the Spring Boot Maven/Gradle plugin. See: https://github.com/paketo-buildpacks/spring-boot and https://buildpacks.io/ +CoherenceResourceStatus defines the observed state of Coherence resource. [cols="1,10,1,1"options="header"] |=== | Field | Description | Type | Required -m| enabled | Enable or disable buildpack detection. The operator will automatically detect Cloud Native Buildpack images but if this auto-detection fails to work correctly for a specific image then this field can be set to true to signify that the image is a buildpack image or false to signify that it is not a buildpack image. m| *bool | false -m| launcher |   m| *string | false +m| phase | The phase of a Coherence resource is a simple, high-level summary of where the Coherence resource is in its lifecycle. The conditions array, the reason and message fields, and the individual container status arrays contain more detail about the pod's status. There are eight possible phase values: + + + +Initialized: The deployment has been accepted by the Kubernetes system. Created: The deployments secondary resources, (e.g. the StatefulSet, Services etc.) have been created. Ready: The StatefulSet for the deployment has the correct number of replicas and ready replicas. Waiting: The deployment's start quorum conditions have not yet been met. Scaling: The number of replicas in the deployment is being scaled up or down. RollingUpgrade: The StatefulSet is performing a rolling upgrade. Stopped: The replica count has been set to zero. Completed: The Coherence resource is running a Job and the Job has completed. Failed: An error occurred reconciling the deployment and its secondary resources. m| ConditionType | false +m| coherenceCluster | The name of the Coherence cluster that this deployment is part of. m| string | false +m| type | The type of the Coherence resource. m| CoherenceType | false +m| replicas | Replicas is the desired number of members in the Coherence deployment represented by the Coherence resource. m| int32 | true +m| currentReplicas | CurrentReplicas is the current number of members in the Coherence deployment represented by the Coherence resource. m| int32 | true +m| readyReplicas | ReadyReplicas is the number of members in the Coherence deployment represented by the Coherence resource that are in the ready state. m| int32 | true +m| active | When the Coherence resource is running a Job, the number of pending and running pods. m| int32 | false +m| succeeded | When the Coherence resource is running a Job, the number of pods which reached phase Succeeded. m| int32 | false +m| failed | When the Coherence resource is running a Job, the number of pods which reached phase Failed. m| int32 | false +m| role | The effective role name for this deployment. This will come from the Spec.Role field if set otherwise the deployment name will be used for the role name m| string | false +m| selector | label query over deployments that should match the replicas count. This is same as the label selector but in the string format to avoid introspection by clients. The string will be in the same format as the query-param syntax. More info about label selectors: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ m| string | false +m| conditions | The status conditions. m| Conditions | false +m| hash | Hash is the hash of the latest applied Coherence spec m| string | false +m| actionsExecuted | ActionsExecuted tracks whether actions were executed m| bool | false +m| jobProbes |   m| []<> | false |=== <
> @@ -245,6 +415,45 @@ m| localPortAdjust | LocalPortAdjust sets the Coherence unicast port adjust valu <
> +=== CoherenceStatefulSetResourceSpec + +CoherenceStatefulSetResourceSpec defines the specification of a Coherence resource. A Coherence resource is typically one or more Pods that perform the same functionality, for example storage members. + +[cols="1,10,1,1"options="header"] +|=== +| Field | Description | Type | Required +m| cluster | The optional name of the Coherence cluster that this Coherence resource belongs to. If this value is set the Pods controlled by this Coherence resource will form a cluster with other Pods controlled by Coherence resources with the same cluster name. If not set the Coherence resource's name will be used as the cluster name. m| *string | false +m| statefulSetAnnotations | StatefulSetAnnotations are free-form yaml that will be added to the Coherence cluster `StatefulSet` as annotations. Any annotations should be placed BELOW this "annotations:" key, for example: + + + +The default behaviour is to copy all annotations from the `Coherence` resource to the `StatefulSet`, specifying any annotations in the `StatefulSetAnnotations` will override this behaviour and only include the `StatefulSetAnnotations`. + + + +annotations: + + foo.io/one: "value1" + + + foo.io/two: "value2" + + + + +see: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[Kubernetes Annotations] m| map[string]string | false +m| volumeClaimTemplates | VolumeClaimTemplates defines extra PVC mappings that will be added to the Coherence Pod. The content of this yaml should match the normal k8s volumeClaimTemplates section of a StatefulSet spec as described in https://kubernetes.io/docs/concepts/storage/persistent-volumes/ Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name. m| []<> | false +m| scaling | The configuration to control safe scaling. m| *<> | false +m| suspendProbe | The configuration of the probe used to signal that services must be suspended before a deployment is stopped. m| *<> | false +m| suspendServicesOnShutdown | A flag controlling whether storage enabled cache services in this deployment will be suspended before the deployment is shutdown or scaled to zero. The action of suspending storage enabled services when the whole deployment is being stopped ensures that cache services with persistence enabled will shut down cleanly without the possibility of Coherence trying to recover and re-balance partitions as Pods are stopped. The default value if not specified is true. m| *bool | false +m| resumeServicesOnStartup | ResumeServicesOnStartup allows the Operator to resume suspended Coherence services when the Coherence container is started. This only applies to storage enabled distributed cache services. This ensures that services that are suspended due to the shutdown of a storage tier, but those services are still running (albeit suspended) in other storage disabled deployments, will be resumed when storage comes back. Note that starting Pods with suspended partitioned cache services may stop the Pod reaching the ready state. The default value if not specified is true. m| *bool | false +m| autoResumeServices | AutoResumeServices is a map of Coherence service names to allow more fine-grained control over which services may be auto-resumed by the operator when a Coherence Pod starts. The key to the map is the name of the Coherence service. This should be the fully qualified name if scoped services are being used in Coherence. The value is a bool, set to `true` to allow the service to be auto-resumed or `false` to not allow the service to be auto-resumed. Adding service names to this list will override any value set in `ResumeServicesOnStartup`, so if the `ResumeServicesOnStartup` field is `false` but there are service names in the `AutoResumeServices`, mapped to `true`, those services will still be resumed. Note that starting Pods with suspended partitioned cache services may stop the Pod reaching the ready state. m| map[string]bool | false +m| suspendServiceTimeout | SuspendServiceTimeout sets the number of seconds to wait for the service suspend call to return (the default is 60 seconds) m| *int | false +m| haBeforeUpdate | Whether to perform a StatusHA test on the cluster before performing an update or deletion. This field can be set to "false" to force through an update even when a Coherence deployment is in an unstable state. The default is true, to always check for StatusHA before updating a Coherence deployment. m| *bool | false +m| allowUnsafeDelete | AllowUnsafeDelete controls whether the Operator will add a finalizer to the Coherence resource so that it can intercept deletion of the resource and initiate a controlled shutdown of the Coherence cluster. The default value is `false`. The primary use for setting this flag to `true` is in CI/CD environments so that cleanup jobs can delete a whole namespace without requiring the Operator to have removed finalizers from any Coherence resources deployed into that namespace. It is not recommended to set this flag to `true` in a production environment, especially when using Coherence persistence features. m| *bool | false +m| actions | Actions to execute once all the Pods are ready after an initial deployment m| []<> | false +m| envFrom | List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. m| []https://{k8s-doc-link}/#envfromsource-v1-core[corev1.EnvFromSource] | false +m| global | Global contains attributes that will be applied to all resources managed by the Coherence Operator. m| *<> | false +m| initResources | InitResources is the optional resource requests and limits for the init-container that the Operator adds to the Pod. + + ref: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + +The Coherence operator does not apply any default resources. m| *https://{k8s-doc-link}/#resourcerequirements-v1-core[corev1.ResourceRequirements] | false +m| rollingUpdateStrategy | The rolling upgrade strategy to use. If present, the value must be one of "UpgradeByPod", "UpgradeByNode" of "OnDelete". If not set, the default is "UpgradeByPod" UpgradeByPod will perform a rolling upgrade one Pod at a time. UpgradeByNode will update all Pods on a Node at the same time. OnDelete will not automatically apply any updates, Pods must be manually deleted for updates to be applied to the restarted Pod. m| *RollingUpdateStrategyType | false +m| rollingUpdateLabel | The name of the Node label to use to group Pods during a rolling upgrade. This field ony applies if RollingUpdateStrategy is set to NodeLabel. If RollingUpdateStrategy is set to NodeLabel and this field is omitted then the rolling upgrade will be by Node. It is the users responsibility to ensure that Nodes actually have the label used for this field. The label should be one of the node labels used to set the Coherence site or rack value. m| *string | false +m| headlessServiceIpFamilies | HeadlessServiceIpFamilies is the optional array of IP families that can be configured for the headless service used for the StatefulSet. m| []https://pkg.go.dev/k8s.io/api/core/v1#IPFamily | false +|=== + +<
> + === CoherenceTracingSpec CoherenceTracingSpec configures Coherence tracing. @@ -839,97 +1048,3 @@ m| ready | Whether this quorum's condition has been met m| bool | true |=== <
> - -=== Coherence - -Coherence is the top level schema for the Coherence API and custom resource definition (CRD). - -[cols="1,10,1,1"options="header"] -|=== -| Field | Description | Type | Required -m| metadata |   m| https://{k8s-doc-link}/#objectmeta-v1-meta[metav1.ObjectMeta] | false -m| spec |   m| <> | false -m| status |   m| <> | false -|=== - -<
> - -=== CoherenceList - -CoherenceList is a list of Coherence resources. - -[cols="1,10,1,1"options="header"] -|=== -| Field | Description | Type | Required -m| metadata |   m| https://{k8s-doc-link}/#listmeta-v1-meta[metav1.ListMeta] | false -m| items |   m| []<> | true -|=== - -<
> - -=== CoherenceResourceStatus - -CoherenceResourceStatus defines the observed state of Coherence resource. - -[cols="1,10,1,1"options="header"] -|=== -| Field | Description | Type | Required -m| phase | The phase of a Coherence resource is a simple, high-level summary of where the Coherence resource is in its lifecycle. The conditions array, the reason and message fields, and the individual container status arrays contain more detail about the pod's status. There are eight possible phase values: + - + -Initialized: The deployment has been accepted by the Kubernetes system. Created: The deployments secondary resources, (e.g. the StatefulSet, Services etc.) have been created. Ready: The StatefulSet for the deployment has the correct number of replicas and ready replicas. Waiting: The deployment's start quorum conditions have not yet been met. Scaling: The number of replicas in the deployment is being scaled up or down. RollingUpgrade: The StatefulSet is performing a rolling upgrade. Stopped: The replica count has been set to zero. Completed: The Coherence resource is running a Job and the Job has completed. Failed: An error occurred reconciling the deployment and its secondary resources. m| ConditionType | false -m| coherenceCluster | The name of the Coherence cluster that this deployment is part of. m| string | false -m| type | The type of the Coherence resource. m| CoherenceType | false -m| replicas | Replicas is the desired number of members in the Coherence deployment represented by the Coherence resource. m| int32 | true -m| currentReplicas | CurrentReplicas is the current number of members in the Coherence deployment represented by the Coherence resource. m| int32 | true -m| readyReplicas | ReadyReplicas is the number of members in the Coherence deployment represented by the Coherence resource that are in the ready state. m| int32 | true -m| active | When the Coherence resource is running a Job, the number of pending and running pods. m| int32 | false -m| succeeded | When the Coherence resource is running a Job, the number of pods which reached phase Succeeded. m| int32 | false -m| failed | When the Coherence resource is running a Job, the number of pods which reached phase Failed. m| int32 | false -m| role | The effective role name for this deployment. This will come from the Spec.Role field if set otherwise the deployment name will be used for the role name m| string | false -m| selector | label query over deployments that should match the replicas count. This is same as the label selector but in the string format to avoid introspection by clients. The string will be in the same format as the query-param syntax. More info about label selectors: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ m| string | false -m| conditions | The status conditions. m| Conditions | false -m| hash | Hash is the hash of the latest applied Coherence spec m| string | false -m| actionsExecuted | ActionsExecuted tracks whether actions were executed m| bool | false -m| jobProbes |   m| []CoherenceJobProbeStatus | false -|=== - -<
> - -=== CoherenceStatefulSetResourceSpec - -CoherenceStatefulSetResourceSpec defines the specification of a Coherence resource. A Coherence resource is typically one or more Pods that perform the same functionality, for example storage members. - -[cols="1,10,1,1"options="header"] -|=== -| Field | Description | Type | Required -m| cluster | The optional name of the Coherence cluster that this Coherence resource belongs to. If this value is set the Pods controlled by this Coherence resource will form a cluster with other Pods controlled by Coherence resources with the same cluster name. If not set the Coherence resource's name will be used as the cluster name. m| *string | false -m| statefulSetAnnotations | StatefulSetAnnotations are free-form yaml that will be added to the Coherence cluster `StatefulSet` as annotations. Any annotations should be placed BELOW this "annotations:" key, for example: + - + -The default behaviour is to copy all annotations from the `Coherence` resource to the `StatefulSet`, specifying any annotations in the `StatefulSetAnnotations` will override this behaviour and only include the `StatefulSetAnnotations`. + - + -annotations: + - foo.io/one: "value1" + + - foo.io/two: "value2" + + - + -see: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[Kubernetes Annotations] m| map[string]string | false -m| volumeClaimTemplates | VolumeClaimTemplates defines extra PVC mappings that will be added to the Coherence Pod. The content of this yaml should match the normal k8s volumeClaimTemplates section of a StatefulSet spec as described in https://kubernetes.io/docs/concepts/storage/persistent-volumes/ Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name. m| []<> | false -m| scaling | The configuration to control safe scaling. m| *<> | false -m| suspendProbe | The configuration of the probe used to signal that services must be suspended before a deployment is stopped. m| *<> | false -m| suspendServicesOnShutdown | A flag controlling whether storage enabled cache services in this deployment will be suspended before the deployment is shutdown or scaled to zero. The action of suspending storage enabled services when the whole deployment is being stopped ensures that cache services with persistence enabled will shut down cleanly without the possibility of Coherence trying to recover and re-balance partitions as Pods are stopped. The default value if not specified is true. m| *bool | false -m| resumeServicesOnStartup | ResumeServicesOnStartup allows the Operator to resume suspended Coherence services when the Coherence container is started. This only applies to storage enabled distributed cache services. This ensures that services that are suspended due to the shutdown of a storage tier, but those services are still running (albeit suspended) in other storage disabled deployments, will be resumed when storage comes back. Note that starting Pods with suspended partitioned cache services may stop the Pod reaching the ready state. The default value if not specified is true. m| *bool | false -m| autoResumeServices | AutoResumeServices is a map of Coherence service names to allow more fine-grained control over which services may be auto-resumed by the operator when a Coherence Pod starts. The key to the map is the name of the Coherence service. This should be the fully qualified name if scoped services are being used in Coherence. The value is a bool, set to `true` to allow the service to be auto-resumed or `false` to not allow the service to be auto-resumed. Adding service names to this list will override any value set in `ResumeServicesOnStartup`, so if the `ResumeServicesOnStartup` field is `false` but there are service names in the `AutoResumeServices`, mapped to `true`, those services will still be resumed. Note that starting Pods with suspended partitioned cache services may stop the Pod reaching the ready state. m| map[string]bool | false -m| suspendServiceTimeout | SuspendServiceTimeout sets the number of seconds to wait for the service suspend call to return (the default is 60 seconds) m| *int | false -m| haBeforeUpdate | Whether to perform a StatusHA test on the cluster before performing an update or deletion. This field can be set to "false" to force through an update even when a Coherence deployment is in an unstable state. The default is true, to always check for StatusHA before updating a Coherence deployment. m| *bool | false -m| allowUnsafeDelete | AllowUnsafeDelete controls whether the Operator will add a finalizer to the Coherence resource so that it can intercept deletion of the resource and initiate a controlled shutdown of the Coherence cluster. The default value is `false`. The primary use for setting this flag to `true` is in CI/CD environments so that cleanup jobs can delete a whole namespace without requiring the Operator to have removed finalizers from any Coherence resources deployed into that namespace. It is not recommended to set this flag to `true` in a production environment, especially when using Coherence persistence features. m| *bool | false -m| actions | Actions to execute once all the Pods are ready after an initial deployment m| []<> | false -m| envFrom | List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. m| []https://{k8s-doc-link}/#envfromsource-v1-core[corev1.EnvFromSource] | false -m| global | Global contains attributes that will be applied to all resources managed by the Coherence Operator. m| *<> | false -m| initResources | InitResources is the optional resource requests and limits for the init-container that the Operator adds to the Pod. + - ref: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + -The Coherence operator does not apply any default resources. m| *https://{k8s-doc-link}/#resourcerequirements-v1-core[corev1.ResourceRequirements] | false -m| rollingUpdateStrategy | The rolling upgrade strategy to use. If present, the value must be one of "UpgradeByPod", "UpgradeByNode" of "OnDelete". If not set, the default is "UpgradeByPod" UpgradeByPod will perform a rolling upgrade one Pod at a time. UpgradeByNode will update all Pods on a Node at the same time. OnDelete will not automatically apply any updates, Pods must be manually deleted for updates to be applied to the restarted Pod. m| *RollingUpdateStrategyType | false -m| rollingUpdateLabel | The name of the Node label to use to group Pods during a rolling upgrade. This field ony applies if RollingUpdateStrategy is set to NodeLabel. If RollingUpdateStrategy is set to NodeLabel and this field is omitted then the rolling upgrade will be by Node. It is the users responsibility to ensure that Nodes actually have the label used for this field. The label should be one of the node labels used to set the Coherence site or rack value. m| *string | false -m| headlessServiceIpFamilies | HeadlessServiceIpFamilies is the optional array of IP families that can be configured for the headless service used for the StatefulSet. m| []https://pkg.go.dev/k8s.io/api/core/v1#IPFamily | false -|=== - -<
> diff --git a/utils/docgen/main.go b/utils/docgen/main.go index 1b87bad9c..64bbc907f 100644 --- a/utils/docgen/main.go +++ b/utils/docgen/main.go @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020, 2023, Oracle and/or its affiliates. + * Copyright (c) 2020, 2025, Oracle and/or its affiliates. * Licensed under the Universal Permissive License v 1.0 as shown at * http://oss.oracle.com/licenses/upl. */ @@ -15,6 +15,7 @@ import ( "go/token" "os" "reflect" + "sort" "strings" "time" ) @@ -105,29 +106,58 @@ func printAPIDocs(paths []string) { // we need to parse once more to now add the self links types = ParseDocumentationFrom(paths) + for _, t := range types { + strukt := t[0] + if strukt.Name == "Coherence" { + printType(t, false) + } + } + + for _, t := range types { + strukt := t[0] + if strukt.Name == "CoherenceJob" { + printType(t, false) + } + } + + sort.Slice(types, func(i, j int) bool { + first := types[i][0] + second := types[j][0] + return first.Name < second.Name + }) + printContents(types) for _, t := range types { strukt := t[0] - if len(t) > 1 { - fmt.Printf("\n=== %s\n\n%s\n\n", strukt.Name, strukt.Doc) - - fmt.Println("[cols=\"1,10,1,1\"options=\"header\"]") - fmt.Println("|===") - fmt.Println("| Field | Description | Type | Required") - fields := t[1:] - - for _, f := range fields { - var d string - if f.Doc == "" { - d = " " - } else { - d = strings.ReplaceAll(f.Doc, "\\n", " +\n") - } - fmt.Println("m|", f.Name, "|", d, "m|", f.Type, "|", f.Mandatory) + if strukt.Name != "Coherence" && strukt.Name != "CoherenceJob" { + printType(t, true) + } + } +} + +func printType(t KubeTypes, back bool) { + strukt := t[0] + if len(t) > 1 { + fmt.Printf("\n=== %s\n\n%s\n\n", strukt.Name, strukt.Doc) + + fmt.Println("[cols=\"1,10,1,1\"options=\"header\"]") + fmt.Println("|===") + fmt.Println("| Field | Description | Type | Required") + fields := t[1:] + + for _, f := range fields { + var d string + if f.Doc == "" { + d = " " + } else { + d = strings.ReplaceAll(f.Doc, "\\n", " +\n") } - fmt.Println("|===") - fmt.Println("") + fmt.Println("m|", f.Name, "|", d, "m|", f.Type, "|", f.Mandatory) + } + fmt.Println("|===") + fmt.Println("") + if back { fmt.Println("<
>") } }