Skip to content

Commit

Permalink
Merge pull request #599 from fluxcd/spec-docs-v1beta2
Browse files Browse the repository at this point in the history
  • Loading branch information
@hiddeco
hiddeco authored Mar 11, 2022
2 parents ccadce6 + 971caf9 commit 7c41249
Show file tree
Hide file tree
Showing 26 changed files with 3,941 additions and 802 deletions.
29 changes: 14 additions & 15 deletions api/v1beta2/artifact_types.go
View file
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
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
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

0 comments on commit 7c41249

Please sign in to comment.