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.
|