Skip to content

Commit

Permalink
fix(operator): Improve API documentation for schema version (#13122)
Browse files Browse the repository at this point in the history
  • Loading branch information
@xperimental
xperimental authored Jun 4, 2024
1 parent 71b861b commit 3a9f50f
Show file tree
Hide file tree
Showing 9 changed files with 88 additions and 61 deletions.
12 changes: 7 additions & 5 deletions operator/apis/loki/v1/lokistack_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion operator/bundle/community-openshift/manifests/loki-operator.clusterserviceversion.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
30 changes: 18 additions & 12 deletions operator/bundle/community-openshift/manifests/loki.grafana.com_lokistacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 18 additions & 12 deletions operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 18 additions & 12 deletions operator/bundle/openshift/manifests/loki.grafana.com_lokistacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
30 changes: 18 additions & 12 deletions operator/config/crd/bases/loki.grafana.com_lokistacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
11 changes: 6 additions & 5 deletions operator/docs/operator/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2594,8 +2594,7 @@ string
(<em>Appears on:</em><a href="#loki-grafana-com-v1-LokiStackStorageStatus">LokiStackStorageStatus</a>, <a href="#loki-grafana-com-v1-ObjectStorageSpec">ObjectStorageSpec</a>)
</p>
<div>
<p>ObjectStorageSchema defines the requirements needed to configure a new
storage schema.</p>
<p>ObjectStorageSchema defines a schema version and the date when it will become effective.</p>
</div>
<table>
<thead>
Expand Down Expand Up @@ -2628,9 +2627,11 @@ StorageSchemaEffectiveDate
</em>
</td>
<td>
<p>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.</p>
<p>EffectiveDate contains a date in YYYY-MM-DD format which is interpreted in the UTC time zone.</p>
<p>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 &ldquo;yesterday&rdquo;.
New schema versions added to the configuration always needs to be placed &ldquo;in the future&rdquo;, so that Loki can start
using it once the day rolls over.</p>
</td>
</tr>
</tbody>
Expand Down

0 comments on commit 3a9f50f

Please sign in to comment.