diff --git a/Makefile b/Makefile index 770fe2592..d1004c14e 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,3 @@ - # Image URL to use all building/pushing image targets IMG ?= fluxcd/source-controller:latest # Produce CRDs that work back to Kubernetes 1.13 @@ -14,7 +13,7 @@ endif all: manager # Run tests -test: generate fmt vet manifests +test: generate fmt vet manifests api-docs go test ./... -coverprofile cover.out # Build manager binary @@ -49,6 +48,10 @@ dev-deploy: manifests manifests: controller-gen $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role paths="./..." output:crd:artifacts:config=config/crd/bases +# Generate API reference documentation +api-docs: gen-crd-api-reference-docs + $(API_REF_GEN) -api-dir=./api/v1alpha1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/api/source.md + # Run go fmt against code fmt: go fmt ./... @@ -84,3 +87,19 @@ CONTROLLER_GEN=$(GOBIN)/controller-gen else CONTROLLER_GEN=$(shell which controller-gen) endif + +# Find or download gen-crd-api-reference-docs +gen-crd-api-reference-docs: +ifeq (, $(shell which gen-crd-api-reference-docs)) + @{ \ + set -e ;\ + API_REF_GEN_TMP_DIR=$$(mktemp -d) ;\ + cd $$API_REF_GEN_TMP_DIR ;\ + go mod init tmp ;\ + go get github.com/ahmetb/gen-crd-api-reference-docs@v0.2.0 ;\ + rm -rf $$API_REF_GEN_TMP_DIR ;\ + } +API_REF_GEN=$(GOBIN)/gen-crd-api-reference-docs +else +API_REF_GEN=$(shell which gen-crd-api-reference-docs) +endif diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go new file mode 100644 index 000000000..f043e59d9 --- /dev/null +++ b/api/v1alpha1/doc.go @@ -0,0 +1,20 @@ +/* +Copyright 2020 The Flux CD contributors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package v1alpha1 contains API Schema definitions for the source v1alpha1 API group +// +kubebuilder:object:generate=true +// +groupName=source.fluxcd.io +package v1alpha1 diff --git a/api/v1alpha1/gitrepository_types.go b/api/v1alpha1/gitrepository_types.go index a6c82a26d..aa15bd9dc 100644 --- a/api/v1alpha1/gitrepository_types.go +++ b/api/v1alpha1/gitrepository_types.go @@ -199,6 +199,8 @@ func (in *GitRepository) GetInterval() metav1.Duration { return in.Spec.Interval } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.spec.url` diff --git a/api/v1alpha1/groupversion_info.go b/api/v1alpha1/groupversion_info.go index 6025b6614..e11f8ed10 100644 --- a/api/v1alpha1/groupversion_info.go +++ b/api/v1alpha1/groupversion_info.go @@ -14,9 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package v1alpha1 contains API Schema definitions for the source v1alpha1 API group -// +kubebuilder:object:generate=true -// +groupName=source.fluxcd.io package v1alpha1 import ( diff --git a/api/v1alpha1/helmchart_types.go b/api/v1alpha1/helmchart_types.go index 521793d0c..558517879 100644 --- a/api/v1alpha1/helmchart_types.go +++ b/api/v1alpha1/helmchart_types.go @@ -147,6 +147,8 @@ func (in *HelmChart) GetInterval() metav1.Duration { return in.Spec.Interval } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:printcolumn:name="Name",type=string,JSONPath=`.spec.name` diff --git a/api/v1alpha1/helmrepository_types.go b/api/v1alpha1/helmrepository_types.go index 1b24fb95a..d724d932e 100644 --- a/api/v1alpha1/helmrepository_types.go +++ b/api/v1alpha1/helmrepository_types.go @@ -146,6 +146,8 @@ func (in *HelmRepository) GetInterval() metav1.Duration { return in.Spec.Interval } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.spec.url` diff --git a/docs/api/source.md b/docs/api/source.md new file mode 100644 index 000000000..b80a9591a --- /dev/null +++ b/docs/api/source.md @@ -0,0 +1,1126 @@ +

Source API reference

+

Packages:

+ +

source.fluxcd.io/v1alpha1

+

Package v1alpha1 contains API Schema definitions for the source v1alpha1 API group

+Resource Types: + +

GitRepository +

+

GitRepository is the Schema for the gitrepositories API

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 +source.fluxcd.io/v1alpha1 +
+kind
+string +		 +GitRepository +
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +GitRepositorySpec + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+url
+ +string + +		 +

The repository URL, can be a HTTP or SSH address.

+
+secretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +(Optional) +

The secret name containing the Git credentials. +For HTTPS repositories the secret must contain username and password +fields. +For SSH repositories the secret must contain identity, identity.pub and +known_hosts fields.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check for repository updates.

+
+timeout
+ + +Kubernetes meta/v1.Duration + + +		 +(Optional) +

The timeout for remote git operations like cloning, default to 20s.

+
+ref
+ + +GitRepositoryRef + + +		 +(Optional) +

The git reference to checkout and monitor for changes, defaults to +master branch.

+
+verify
+ + +GitRepositoryVerification + + +		 +(Optional) +

Verify OpenPGP signature for the commit that HEAD points to.

+
+
+status
+ + +GitRepositoryStatus + + +		 +
+
+
+

HelmChart +

+

HelmChart is the Schema for the helmcharts API

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 +source.fluxcd.io/v1alpha1 +
+kind
+string +		 +HelmChart +
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +HelmChartSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + +
+name
+ +string + +		 +

The name of the Helm chart, as made available by the referenced +Helm repository.

+
+version
+ +string + +		 +(Optional) +

The chart version semver expression, defaults to latest when +omitted.

+
+helmRepositoryRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +

The name of the HelmRepository the chart is available at.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check the Helm repository for updates.

+
+
+status
+ + +HelmChartStatus + + +		 +
+
+
+

HelmRepository +

+

HelmRepository is the Schema for the helmrepositories API

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 +source.fluxcd.io/v1alpha1 +
+kind
+string +		 +HelmRepository +
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +HelmRepositorySpec + + +		 +
+
+ + + + + + + + + + + + + +
+url
+ +string + +		 +

The Helm repository URL, a valid URL contains at least a +protocol and host.

+
+secretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +(Optional) +

The name of the secret containing authentication credentials +for the Helm repository. +For HTTP/S basic auth the secret must contain username and password +fields. +For TLS the secret must contain caFile, keyFile and caCert fields.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check the upstream for updates.

+
+
+status
+ + +HelmRepositoryStatus + + +		 +
+
+
+

Artifact +

+

+(Appears on: +GitRepositoryStatus, +HelmChartStatus, +HelmRepositoryStatus) +

+

Artifact represents the output of a source synchronisation

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+path
+ +string + +		 +

Path is the local file path of this artifact.

+
+url
+ +string + +		 +

URL is the HTTP address of this artifact.

+
+revision
+ +string + +		 +(Optional) +

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.

+
+lastUpdateTime
+ + +Kubernetes meta/v1.Time + + +		 +

LastUpdateTime is the timestamp corresponding to the last +update of this artifact.

+
+
+
+

GitRepositoryRef +

+

+(Appears on: +GitRepositorySpec) +

+

GitRepositoryRef defines the git ref used for pull and checkout operations.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+branch
+ +string + +		 +(Optional) +

The git branch to checkout, defaults to master.

+
+tag
+ +string + +		 +(Optional) +

The git tag to checkout, takes precedence over branch.

+
+semver
+ +string + +		 +(Optional) +

The git tag semver expression, takes precedence over tag.

+
+commit
+ +string + +		 +(Optional) +

The git commit sha to checkout, if specified tag filters will be ignored.

+
+
+
+

GitRepositorySpec +

+

+(Appears on: +GitRepository) +

+

GitRepositorySpec defines the desired state of a Git repository.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+url
+ +string + +		 +

The repository URL, can be a HTTP or SSH address.

+
+secretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +(Optional) +

The secret name containing the Git credentials. +For HTTPS repositories the secret must contain username and password +fields. +For SSH repositories the secret must contain identity, identity.pub and +known_hosts fields.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check for repository updates.

+
+timeout
+ + +Kubernetes meta/v1.Duration + + +		 +(Optional) +

The timeout for remote git operations like cloning, default to 20s.

+
+ref
+ + +GitRepositoryRef + + +		 +(Optional) +

The git reference to checkout and monitor for changes, defaults to +master branch.

+
+verify
+ + +GitRepositoryVerification + + +		 +(Optional) +

Verify OpenPGP signature for the commit that HEAD points to.

+
+
+
+

GitRepositoryStatus +

+

+(Appears on: +GitRepository) +

+

GitRepositoryStatus defines the observed state of a Git repository.

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +[]SourceCondition + + +		 +(Optional) +
+url
+ +string + +		 +(Optional) +

URL is the download link for the artifact output of the last repository +sync.

+
+artifact
+ + +Artifact + + +		 +(Optional) +

Artifact represents the output of the last successful repository sync.

+
+
+
+

GitRepositoryVerification +

+

+(Appears on: +GitRepositorySpec) +

+

GitRepositoryVerification defines the OpenPGP signature verification process.

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+mode
+ +string + +		 +

Mode describes what git object should be verified, currently (‘head’).

+
+secretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +

The secret name containing the public keys of all trusted git authors.

+
+
+
+

HelmChartSpec +

+

+(Appears on: +HelmChart) +

+

HelmChartSpec defines the desired state of a Helm chart.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

The name of the Helm chart, as made available by the referenced +Helm repository.

+
+version
+ +string + +		 +(Optional) +

The chart version semver expression, defaults to latest when +omitted.

+
+helmRepositoryRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +

The name of the HelmRepository the chart is available at.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check the Helm repository for updates.

+
+
+
+

HelmChartStatus +

+

+(Appears on: +HelmChart) +

+

HelmChartStatus defines the observed state of the HelmChart.

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +[]SourceCondition + + +		 +(Optional) +
+url
+ +string + +		 +(Optional) +

URL is the download link for the last chart pulled.

+
+artifact
+ + +Artifact + + +		 +(Optional) +

Artifact represents the output of the last successful chart sync.

+
+
+
+

HelmRepositorySpec +

+

+(Appears on: +HelmRepository) +

+

HelmRepositorySpec defines the reference to a Helm repository.

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+url
+ +string + +		 +

The Helm repository URL, a valid URL contains at least a +protocol and host.

+
+secretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +(Optional) +

The name of the secret containing authentication credentials +for the Helm repository. +For HTTP/S basic auth the secret must contain username and password +fields. +For TLS the secret must contain caFile, keyFile and caCert fields.

+
+interval
+ + +Kubernetes meta/v1.Duration + + +		 +

The interval at which to check the upstream for updates.

+
+
+
+

HelmRepositoryStatus +

+

+(Appears on: +HelmRepository) +

+

HelmRepositoryStatus defines the observed state of the HelmRepository.

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +[]SourceCondition + + +		 +(Optional) +
+url
+ +string + +		 +(Optional) +

URL is the download link for the last index fetched.

+
+artifact
+ + +Artifact + + +		 +(Optional) +

Artifact represents the output of the last successful repository sync.

+
+
+
+

Source +

+

Source interface must be supported by all API types.

+

SourceCondition +

+

+(Appears on: +GitRepositoryStatus, +HelmChartStatus, +HelmRepositoryStatus) +

+

SourceCondition contains condition information for a source.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+type
+ +string + +		 +

Type of the condition, currently (‘Ready’).

+
+status
+ + +Kubernetes core/v1.ConditionStatus + + +		 +

Status of the condition, one of (‘True’, ‘False’, ‘Unknown’).

+
+lastTransitionTime
+ + +Kubernetes meta/v1.Time + + +		 +

LastTransitionTime is the timestamp corresponding to the last status +change of this condition.

+
+reason
+ +string + +		 +

Reason is a brief machine readable explanation for the condition’s last +transition.

+
+message
+ +string + +		 +(Optional) +

Message is a human readable description of the details of the last +transition, complementing reason.

+
+
+
+
+

This page was automatically generated with gen-crd-api-reference-docs

+
diff --git a/hack/api-docs/config.json b/hack/api-docs/config.json new file mode 100644 index 000000000..87c291ac9 --- /dev/null +++ b/hack/api-docs/config.json @@ -0,0 +1,24 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/api-docs/template/members.tpl b/hack/api-docs/template/members.tpl new file mode 100644 index 000000000..26e7251e4 --- /dev/null +++ b/hack/api-docs/template/members.tpl @@ -0,0 +1,46 @@ +{{ define "members" }} + {{ range .Members }} + {{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
+
+ + {{ template "members" .Type }} +
+ {{ end }} + + + {{ end }} + {{ end }} +{{ end }} diff --git a/hack/api-docs/template/pkg.tpl b/hack/api-docs/template/pkg.tpl new file mode 100644 index 000000000..f2b3140f2 --- /dev/null +++ b/hack/api-docs/template/pkg.tpl @@ -0,0 +1,46 @@ +{{ define "packages" }} +

Source API reference

+ + {{ with .packages}} +

Packages:

+ + {{ end}} + + {{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} + {{ safe (renderComments .) }} + {{ end }} + {{ end }} + + Resource Types: + + + + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} + {{ end }} + +
+

This page was automatically generated with gen-crd-api-reference-docs

+
+{{ end }} diff --git a/hack/api-docs/template/type.tpl b/hack/api-docs/template/type.tpl new file mode 100644 index 000000000..cd2fa6981 --- /dev/null +++ b/hack/api-docs/template/type.tpl @@ -0,0 +1,60 @@ +{{ define "type" }} +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+ + {{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{ $prev = . }} + {{ typeDisplayName . }} + {{- end -}} + ) +

+ {{ end }} + + {{ with .CommentLines }} + {{ safe (renderComments .) }} + {{ end }} + + {{ if .Members }} +
+
+ + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" . }} + +
FieldDescription
+ apiVersion
+ string		 + {{ apiGroup . }} +
+ kind
+ string + 		+ {{ .Name.Name }} +
+
+
+ {{ end }} +{{ end }}