Skip to content

API v1beta2 spec docs #599

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
hiddeco merged 9 commits into from
Mar 11, 2022
Merged

API v1beta2 spec docs #599

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5832296
Document Bucket API v1beta2 spec
hiddeco Feb 3, 2022
86d1d80
Document HelmRepository API v1beta2 spec
hiddeco Feb 7, 2022
cbffd82
Document GitRepository API v1beta2 spec
hiddeco Feb 8, 2022
f59b48c
Document HelmChart API v1beta2 spec
darkowlzz Feb 14, 2022
9e73bfa
docs/spec: Update the outputs
darkowlzz Feb 25, 2022
8d4fce1
Add more details in helmchart spec doc
darkowlzz Feb 25, 2022
abf29da
docs/spec: document Bucket's Azure Blob support
hiddeco Mar 8, 2022
ff536e1
doc/spec: use --field-manager in kubectl examples
hiddeco Mar 9, 2022
971caf9
controllers: finetune `eventLogf` (variant) docs
hiddeco Mar 10, 2022
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
29 changes: 14 additions & 15 deletions api/v1beta2/artifact_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,32 +23,31 @@ import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// Artifact represents the output of a Source synchronisation.
// Artifact represents the output of a Source reconciliation.
type Artifact struct {
// Path is the relative file path of this Artifact.
// It can be used to locate the Artifact file in the root of the Artifact
// storage on the local file system of the controller managing the Source.
// Path is the relative file path of the Artifact. It can be used to locate
// the file in the root of the Artifact storage on the local file system of
// the controller managing the Source.
// +required
Path string `json:"path"`

// URL is the HTTP address of this artifact.
// It is used by the consumers of the artifacts to fetch and use the
// artifacts. It is expected to be resolvable from within the cluster.
// URL is the HTTP address of the Artifact as exposed by the controller
// managing the Source. It can be used to retrieve the Artifact for
// consumption, e.g. by another controller applying the Artifact contents.
// +required
URL string `json:"url"`

// Revision is a human readable identifier traceable in the origin source
// system. It can be a Git commit SHA, Git tag, a Helm index timestamp, a Helm
// chart version, etc.
// Revision is a human-readable identifier traceable in the origin source
// system. It can be a Git commit SHA, Git tag, a Helm chart version, etc.
// +optional
Revision string `json:"revision"`

// Checksum is the SHA256 checksum of the artifact.
// Checksum is the SHA256 checksum of the Artifact file.
// +optional
Checksum string `json:"checksum"`

// LastUpdateTime is the timestamp corresponding to the last update of this
// artifact.
// LastUpdateTime is the timestamp corresponding to the last update of the
// Artifact.
// +required
LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`

Expand All @@ -67,14 +66,14 @@ func (in *Artifact) HasRevision(revision string) bool {
}

// ArtifactDir returns the artifact dir path in the form of
// <source-kind>/<source-namespace>/<source-name>.
// '<kind>/<namespace>/<name>'.
func ArtifactDir(kind, namespace, name string) string {
kind = strings.ToLower(kind)
return path.Join(kind, namespace, name)
}

// ArtifactPath returns the artifact path in the form of
// <source-kind>/<source-namespace>/<source-name>/<artifact-filename>.
// '<kind>/<namespace>/name>/<filename>'.
func ArtifactPath(kind, namespace, name, filename string) string {
return path.Join(ArtifactDir(kind, namespace, name), filename)
}
77 changes: 40 additions & 37 deletions api/v1beta2/bucket_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,46 +31,57 @@ const (
)

const (
// GenericBucketProvider for any S3 API compatible storage Bucket.
GenericBucketProvider string = "generic"
AmazonBucketProvider string = "aws"
GoogleBucketProvider string = "gcp"
AzureBucketProvider string = "azure"
// AmazonBucketProvider for an AWS S3 object storage Bucket.
// Provides support for retrieving credentials from the AWS EC2 service.
AmazonBucketProvider string = "aws"
// GoogleBucketProvider for a Google Cloud Storage Bucket.
// Provides support for authentication using a workload identity.
GoogleBucketProvider string = "gcp"
// AzureBucketProvider for an Azure Blob Storage Bucket.
// Provides support for authentication using a Service Principal,
// Managed Identity or Shared Key.
AzureBucketProvider string = "azure"
)

// BucketSpec defines the desired state of an S3 compatible bucket
// BucketSpec specifies the required configuration to produce an Artifact for
// an object storage bucket.
type BucketSpec struct {
// The S3 compatible storage provider name, default ('generic').
// Provider of the object storage bucket.
// Defaults to 'generic', which expects an S3 (API) compatible object
// storage.
// +kubebuilder:validation:Enum=generic;aws;gcp;azure
// +kubebuilder:default:=generic
// +optional
Provider string `json:"provider,omitempty"`

// The bucket name.
// BucketName is the name of the object storage bucket.
// +required
BucketName string `json:"bucketName"`

// The bucket endpoint address.
// Endpoint is the object storage address the BucketName is located at.
// +required
Endpoint string `json:"endpoint"`

// Insecure allows connecting to a non-TLS S3 HTTP endpoint.
// Insecure allows connecting to a non-TLS HTTP Endpoint.
// +optional
Insecure bool `json:"insecure,omitempty"`

// The bucket region.
// Region of the Endpoint where the BucketName is located in.
// +optional
Region string `json:"region,omitempty"`

// The name of the secret containing authentication credentials
// SecretRef specifies the Secret containing authentication credentials
// for the Bucket.
// +optional
SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`

// The interval at which to check for bucket updates.
// Interval at which to check the Endpoint for updates.
// +required
Interval metav1.Duration `json:"interval"`

// The timeout for fetch operations, defaults to 60s.
// Timeout for fetch operations, defaults to 60s.
// +kubebuilder:default="60s"
// +optional
Timeout *metav1.Duration `json:"timeout,omitempty"`
Expand All @@ -81,43 +92,48 @@ type BucketSpec struct {
// +optional
Ignore *string `json:"ignore,omitempty"`

// This flag tells the controller to suspend the reconciliation of this source.
// Suspend tells the controller to suspend the reconciliation of this
// Bucket.
// +optional
Suspend bool `json:"suspend,omitempty"`

// AccessFrom defines an Access Control List for allowing cross-namespace references to this object.
// AccessFrom specifies an Access Control List for allowing cross-namespace
// references to this object.
// NOTE: Not implemented, provisional as of https://github.com/fluxcd/flux2/pull/2092
// +optional
AccessFrom *acl.AccessFrom `json:"accessFrom,omitempty"`
}

// BucketStatus defines the observed state of a bucket
// BucketStatus records the observed state of a Bucket.
type BucketStatus struct {
// ObservedGeneration is the last observed generation.
// ObservedGeneration is the last observed generation of the Bucket object.
// +optional
ObservedGeneration int64 `json:"observedGeneration,omitempty"`

// Conditions holds the conditions for the Bucket.
// +optional
Conditions []metav1.Condition `json:"conditions,omitempty"`

// URL is the fetch link for the artifact output of the last Bucket sync.
// URL is the dynamic fetch link for the latest Artifact.
// It is provided on a "best effort" basis, and using the precise
// BucketStatus.Artifact data is recommended.
// +optional
URL string `json:"url,omitempty"`

// Artifact represents the output of the last successful Bucket sync.
// Artifact represents the last successful Bucket reconciliation.
// +optional
Artifact *Artifact `json:"artifact,omitempty"`

meta.ReconcileRequestStatus `json:",inline"`
}

const (
// BucketOperationSucceededReason represents the fact that the bucket listing and
// fetch operations succeeded.
// BucketOperationSucceededReason signals that the Bucket listing and fetch
// operations succeeded.
BucketOperationSucceededReason string = "BucketOperationSucceeded"

// BucketOperationFailedReason represents the fact that the bucket listing or
// fetch operations failed.
// BucketOperationFailedReason signals that the Bucket listing or fetch
// operations failed.
BucketOperationFailedReason string = "BucketOperationFailed"
)

Expand All @@ -136,23 +152,11 @@ func (in Bucket) GetRequeueAfter() time.Duration {
return in.Spec.Interval.Duration
}

// GetInterval returns the interval at which the source is reconciled.
// Deprecated: use GetRequeueAfter instead.
func (in Bucket) GetInterval() metav1.Duration {
return in.Spec.Interval
}

// GetArtifact returns the latest artifact from the source if present in the status sub-resource.
func (in *Bucket) GetArtifact() *Artifact {
return in.Status.Artifact
}

// GetStatusConditions returns a pointer to the Status.Conditions slice.
// Deprecated: use GetConditions instead.
func (in *Bucket) GetStatusConditions() *[]metav1.Condition {
return &in.Status.Conditions
}

// +genclient
// +genclient:Namespaced
// +kubebuilder:storageversion
Expand All @@ -163,7 +167,7 @@ func (in *Bucket) GetStatusConditions() *[]metav1.Condition {
// +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status",description=""
// +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message",description=""

// Bucket is the Schema for the buckets API
// Bucket is the Schema for the buckets API.
type Bucket struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Expand All @@ -173,9 +177,8 @@ type Bucket struct {
Status BucketStatus `json:"status,omitempty"`
}

// BucketList contains a list of Bucket objects.
// +kubebuilder:object:root=true

// BucketList contains a list of Bucket
type BucketList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Expand Down
36 changes: 22 additions & 14 deletions api/v1beta2/condition_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,33 +19,41 @@ package v1beta2
const SourceFinalizer = "finalizers.fluxcd.io"

const (
// ArtifactOutdatedCondition indicates the current Artifact of the Source is outdated.
// This is a "negative polarity" or "abnormal-true" type, and is only present on the resource if it is True.
// ArtifactOutdatedCondition indicates the current Artifact of the Source
// is outdated.
// This is a "negative polarity" or "abnormal-true" type, and is only
// present on the resource if it is True.
ArtifactOutdatedCondition string = "ArtifactOutdated"

// SourceVerifiedCondition indicates the integrity of the Source has been verified. If True, the integrity check
// succeeded. If False, it failed. The Condition is only present on the resource if the integrity has been verified.
// SourceVerifiedCondition indicates the integrity of the Source has been
// verified. If True, the integrity check succeeded. If False, it failed.
// The Condition is only present on the resource if the integrity has been
// verified.
SourceVerifiedCondition string = "SourceVerified"

// FetchFailedCondition indicates a transient or persistent fetch failure of an upstream Source.
// If True, observations on the upstream Source revision may be impossible, and the Artifact available for the
// Source may be outdated.
// This is a "negative polarity" or "abnormal-true" type, and is only present on the resource if it is True.
// FetchFailedCondition indicates a transient or persistent fetch failure
// of an upstream Source.
// If True, observations on the upstream Source revision may be impossible,
// and the Artifact available for the Source may be outdated.
// This is a "negative polarity" or "abnormal-true" type, and is only
// present on the resource if it is True.
FetchFailedCondition string = "FetchFailed"

// BuildFailedCondition indicates a transient or persistent build failure of a Source's Artifact.
// If True, the Source can be in an ArtifactOutdatedCondition
// BuildFailedCondition indicates a transient or persistent build failure
// of a Source's Artifact.
// If True, the Source can be in an ArtifactOutdatedCondition.
BuildFailedCondition string = "BuildFailed"
)

const (
// URLInvalidReason represents the fact that a given source has an invalid URL.
// URLInvalidReason signals that a given Source has an invalid URL.
URLInvalidReason string = "URLInvalid"

// StorageOperationFailedReason signals a failure caused by a storage operation.
// StorageOperationFailedReason signals a failure caused by a storage
// operation.
StorageOperationFailedReason string = "StorageOperationFailed"

// AuthenticationFailedReason represents the fact that a given secret does not
// have the required fields or the provided credentials do not match.
// AuthenticationFailedReason signals that a Secret does not have the
// required fields, or the provided credentials do not match.
AuthenticationFailedReason string = "AuthenticationFailed"
)
Loading