From 3a9f50f5099a02e662b8ac10ddad0b36cd844161 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 4 Jun 2024 19:46:19 +0200 Subject: [PATCH] fix(operator): Improve API documentation for schema version (#13122) --- operator/apis/loki/v1/lokistack_types.go | 12 ++++---- .../loki-operator.clusterserviceversion.yaml | 2 +- .../loki.grafana.com_lokistacks.yaml | 30 +++++++++++-------- .../loki-operator.clusterserviceversion.yaml | 2 +- .../loki.grafana.com_lokistacks.yaml | 30 +++++++++++-------- .../loki-operator.clusterserviceversion.yaml | 2 +- .../loki.grafana.com_lokistacks.yaml | 30 +++++++++++-------- .../bases/loki.grafana.com_lokistacks.yaml | 30 +++++++++++-------- operator/docs/operator/api.md | 11 +++---- 9 files changed, 88 insertions(+), 61 deletions(-) diff --git a/operator/apis/loki/v1/lokistack_types.go b/operator/apis/loki/v1/lokistack_types.go index f347feccf9c2..185f6bb1d846 100644 --- a/operator/apis/loki/v1/lokistack_types.go +++ b/operator/apis/loki/v1/lokistack_types.go @@ -556,8 +556,7 @@ const ( ObjectStorageSchemaV13 ObjectStorageSchemaVersion = "v13" ) -// ObjectStorageSchema defines the requirements needed to configure a new -// storage schema. +// ObjectStorageSchema defines a schema version and the date when it will become effective. type ObjectStorageSchema struct { // Version for writing and reading logs. // @@ -566,9 +565,12 @@ type ObjectStorageSchema struct { // +operator-sdk:csv:customresourcedefinitions:type=spec,xDescriptors={"urn:alm:descriptor:com.tectonic.ui:select:v11","urn:alm:descriptor:com.tectonic.ui:select:v12","urn:alm:descriptor:com.tectonic.ui:select:v13"},displayName="Version" Version ObjectStorageSchemaVersion `json:"version"` - // EffectiveDate is the date in UTC that the schema will be applied on. - // To ensure readibility of logs, this date should be before the current - // date in UTC. + // EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + // + // The configuration always needs at least one schema that is currently valid. This means that when creating a new + // LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + // New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + // using it once the day rolls over. // // +required // +kubebuilder:validation:Required diff --git a/operator/bundle/community-openshift/manifests/loki-operator.clusterserviceversion.yaml b/operator/bundle/community-openshift/manifests/loki-operator.clusterserviceversion.yaml index fdd8b98c0e3b..b77a51c3574a 100644 --- a/operator/bundle/community-openshift/manifests/loki-operator.clusterserviceversion.yaml +++ b/operator/bundle/community-openshift/manifests/loki-operator.clusterserviceversion.yaml @@ -150,7 +150,7 @@ metadata: categories: OpenShift Optional, Logging & Tracing certified: "false" containerImage: docker.io/grafana/loki-operator:0.6.1 - createdAt: "2024-06-03T10:01:23Z" + createdAt: "2024-06-04T16:17:47Z" description: The Community Loki Operator provides Kubernetes native deployment and management of Loki and related logging components. features.operators.openshift.io/disconnected: "true" diff --git a/operator/bundle/community-openshift/manifests/loki.grafana.com_lokistacks.yaml b/operator/bundle/community-openshift/manifests/loki.grafana.com_lokistacks.yaml index b5ca838eff14..df256e183a01 100644 --- a/operator/bundle/community-openshift/manifests/loki.grafana.com_lokistacks.yaml +++ b/operator/bundle/community-openshift/manifests/loki.grafana.com_lokistacks.yaml @@ -598,15 +598,18 @@ spec: version: v11 description: Schemas for reading and writing logs. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: @@ -3826,15 +3829,18 @@ spec: Schemas is a list of schemas which have been applied to the LokiStack. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: diff --git a/operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml b/operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml index 4a91115484c9..153de2325864 100644 --- a/operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml +++ b/operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml @@ -150,7 +150,7 @@ metadata: categories: OpenShift Optional, Logging & Tracing certified: "false" containerImage: docker.io/grafana/loki-operator:0.6.1 - createdAt: "2024-06-03T10:01:22Z" + createdAt: "2024-06-04T16:17:41Z" description: The Community Loki Operator provides Kubernetes native deployment and management of Loki and related logging components. operators.operatorframework.io/builder: operator-sdk-unknown diff --git a/operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml b/operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml index f2ccf71f8c23..b349edbecec9 100644 --- a/operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml +++ b/operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml @@ -598,15 +598,18 @@ spec: version: v11 description: Schemas for reading and writing logs. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: @@ -3826,15 +3829,18 @@ spec: Schemas is a list of schemas which have been applied to the LokiStack. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: diff --git a/operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml b/operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml index a5b77fdc6e23..c2f743258fa4 100644 --- a/operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml +++ b/operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml @@ -150,7 +150,7 @@ metadata: categories: OpenShift Optional, Logging & Tracing certified: "false" containerImage: quay.io/openshift-logging/loki-operator:0.1.0 - createdAt: "2024-06-03T10:01:25Z" + createdAt: "2024-06-04T16:17:54Z" description: | The Loki Operator for OCP provides a means for configuring and managing a Loki stack for cluster logging. ## Prerequisites and Requirements diff --git a/operator/bundle/openshift/manifests/loki.grafana.com_lokistacks.yaml b/operator/bundle/openshift/manifests/loki.grafana.com_lokistacks.yaml index 595812b06f2d..fe4d81f5646f 100644 --- a/operator/bundle/openshift/manifests/loki.grafana.com_lokistacks.yaml +++ b/operator/bundle/openshift/manifests/loki.grafana.com_lokistacks.yaml @@ -598,15 +598,18 @@ spec: version: v11 description: Schemas for reading and writing logs. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: @@ -3826,15 +3829,18 @@ spec: Schemas is a list of schemas which have been applied to the LokiStack. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: diff --git a/operator/config/crd/bases/loki.grafana.com_lokistacks.yaml b/operator/config/crd/bases/loki.grafana.com_lokistacks.yaml index b38108dd80a1..cc971fd0c562 100644 --- a/operator/config/crd/bases/loki.grafana.com_lokistacks.yaml +++ b/operator/config/crd/bases/loki.grafana.com_lokistacks.yaml @@ -580,15 +580,18 @@ spec: version: v11 description: Schemas for reading and writing logs. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: @@ -3808,15 +3811,18 @@ spec: Schemas is a list of schemas which have been applied to the LokiStack. items: - description: |- - ObjectStorageSchema defines the requirements needed to configure a new - storage schema. + description: ObjectStorageSchema defines a schema version and + the date when it will become effective. properties: effectiveDate: description: |- - EffectiveDate is the date in UTC that the schema will be applied on. - To ensure readibility of logs, this date should be before the current - date in UTC. + EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone. + + + The configuration always needs at least one schema that is currently valid. This means that when creating a new + LokiStack it is recommended to add a schema with the latest available version and an effective date of "yesterday". + New schema versions added to the configuration always needs to be placed "in the future", so that Loki can start + using it once the day rolls over. pattern: ^([0-9]{4,})([-]([0-9]{2})){2}$ type: string version: diff --git a/operator/docs/operator/api.md b/operator/docs/operator/api.md index 6c5c47775a4e..e6e5a65765d1 100644 --- a/operator/docs/operator/api.md +++ b/operator/docs/operator/api.md @@ -2594,8 +2594,7 @@ string (Appears on:LokiStackStorageStatus, ObjectStorageSpec)

-

ObjectStorageSchema defines the requirements needed to configure a new -storage schema.

+

ObjectStorageSchema defines a schema version and the date when it will become effective.

@@ -2628,9 +2627,11 @@ StorageSchemaEffectiveDate
-

EffectiveDate is the date in UTC that the schema will be applied on. -To ensure readibility of logs, this date should be before the current -date in UTC.

+

EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone.

+

The configuration always needs at least one schema that is currently valid. This means that when creating a new +LokiStack it is recommended to add a schema with the latest available version and an effective date of “yesterday”. +New schema versions added to the configuration always needs to be placed “in the future”, so that Loki can start +using it once the day rolls over.