151 lines
4.2 KiB
Markdown
151 lines
4.2 KiB
Markdown
# Common
|
|
|
|
Common defines resources used across all source types.
|
|
|
|
## Specification
|
|
|
|
### Source interface
|
|
|
|
Source objects should adhere to the `Source` interface. This interface exposes the [interval](#source-synchronization)
|
|
and [artifact](#source-status) of the source to clients without the prerequisite of knowing the source kind:
|
|
|
|
````go
|
|
type Source interface {
|
|
// GetInterval returns the interval at which the source is updated.
|
|
GetInterval() metav1.Duration
|
|
|
|
// GetArtifact returns the latest artifact from the source, or nil.
|
|
GetArtifact() *Artifact
|
|
}
|
|
````
|
|
|
|
### Source synchronization
|
|
|
|
Source objects should contain a `spec.interval` field that tells the controller at which interval to check for updates:
|
|
|
|
```go
|
|
type SourceSpec struct {
|
|
// The interval at which to check for source updates.
|
|
// +required
|
|
Interval metav1.Duration `json:"interval"`
|
|
}
|
|
```
|
|
|
|
Valid time units are `s`, `m` and `h` e.g. `interval: 5m`.
|
|
|
|
The controller can be told to check for updates right away by setting an annotation on source objects:
|
|
|
|
```go
|
|
const (
|
|
// SyncAtAnnotation is the timestamp corresponding to an on-demand source sync.
|
|
SyncAtAnnotation string = "source.fluxcd.io/syncAt"
|
|
)
|
|
```
|
|
|
|
Trigger source sync example:
|
|
|
|
```bash
|
|
kubectl annotate --overwrite gitrepository/podinfo source.fluxcd.io/syncAt="$(date +%s)"
|
|
```
|
|
|
|
### Source status
|
|
|
|
Source objects should contain a status sub-resource that embeds an artifact object:
|
|
|
|
```go
|
|
// Artifact represents the output of a source synchronisation
|
|
type Artifact struct {
|
|
// Path is the local file path of this artifact.
|
|
// +required
|
|
Path string `json:"path"`
|
|
|
|
// URL is the HTTP address of this artifact.
|
|
// +required
|
|
URL string `json:"url"`
|
|
|
|
// Revision is a human readable identifier traceable in the origin source system.
|
|
// It can be a commit sha, git tag, a helm index timestamp,
|
|
// a helm chart version, a checksum, etc.
|
|
// +optional
|
|
Revision string `json:"revision"`
|
|
|
|
// LastUpdateTime is the timestamp corresponding to the last
|
|
// update of this artifact.
|
|
// +required
|
|
LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`
|
|
}
|
|
```
|
|
|
|
### Source condition
|
|
|
|
> **Note:** to be replaced with <https://github.com/kubernetes/enhancements/pull/1624>
|
|
> once made available.
|
|
|
|
```go
|
|
// SourceCondition contains condition information for a source.
|
|
type SourceCondition struct {
|
|
// Type of the condition, currently ('Ready').
|
|
// +required
|
|
Type string `json:"type"`
|
|
|
|
// Status of the condition, one of ('True', 'False', 'Unknown').
|
|
// +required
|
|
Status corev1.ConditionStatus `json:"status"`
|
|
|
|
// LastTransitionTime is the timestamp corresponding to the last status
|
|
// change of this condition.
|
|
// +required
|
|
LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty"`
|
|
|
|
// Reason is a brief machine readable explanation for the condition's last
|
|
// transition.
|
|
// +required
|
|
Reason string `json:"reason,omitempty"`
|
|
|
|
// Message is a human readable description of the details of the last
|
|
// transition, complementing reason.
|
|
// +optional
|
|
Message string `json:"message,omitempty"`
|
|
}
|
|
```
|
|
|
|
#### Types
|
|
|
|
```go
|
|
const (
|
|
// ReadyCondition represents the fact that a given source is in ready state.
|
|
ReadyCondition string = "Ready"
|
|
)
|
|
```
|
|
|
|
#### Reasons
|
|
|
|
```go
|
|
const (
|
|
// InitializingReason represents the fact that a given source is being initialized.
|
|
InitializingReason string = "Initializing"
|
|
|
|
// URLInvalidReason represents the fact that a given source has an invalid URL.
|
|
URLInvalidReason string = "URLInvalid"
|
|
|
|
// 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 string = "AuthenticationFailed"
|
|
|
|
// VerificationFailedReason represents the fact that the cryptographic provenance
|
|
// verification for the source failed.
|
|
VerificationFailedReason string = "VerificationFailed"
|
|
|
|
// ProgressingReason represents the fact that a source reconciliation
|
|
// is underway.
|
|
ProgressingReason string = "Progressing"
|
|
)
|
|
```
|
|
|
|
## Examples
|
|
|
|
See the [Git repository](gitrepositories.md) and [Helm chart](helmcharts.md) APIs.
|