airship
/
sip
Code Issues Proposed changes

Generate api docs for CRD types 

Signed-off-by: Sean Eagan <seaneagan1@gmail.com>
Change-Id: I646579ed39f1b7bd2eefd34473d653cedbec9adf
This commit is contained in:
Sean Eagan 2021-01-21 13:50:43 -06:00
parent 353fed3df3
commit 89fbb94953
9 changed files with 688 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Makefile
View File

@ -38,7 +38,7 @@ kubernetes:
all: manager
# Run tests
test: generate fmt vet manifests lint
test: generate fmt vet manifests lint api-docs
go test ./... -coverprofile cover.out
# Build manager binary
@ -87,6 +87,26 @@ docker-build:
docker-push:
docker push ${IMG}
# Generate API reference documentation
api-docs: gen-crd-api-reference-docs
$(API_REF_GEN) -api-dir=./pkg/api/v1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/api/sipcluster.md
# 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
# find or download controller-gen
# download controller-gen if necessary
controller-gen:

461
docs/api/sipcluster.md Normal file
View File

@ -0,0 +1,461 @@
<h1>SIPCluster API reference</h1>
<p>Packages:</p>
<ul class="simple">
<li>
<a href="#airship.airshipit.org%2fv1">airship.airshipit.org/v1</a>
</li>
</ul>
<h2 id="airship.airshipit.org/v1">airship.airshipit.org/v1</h2>
<p>Package v1 contains API Schema definitions for the airship v1 API group</p>
Resource Types:
<ul class="simple"></ul>
<h3 id="airship.airshipit.org/v1.InfraConfig">InfraConfig
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.SIPClusterSpec">SIPClusterSpec</a>)
</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>serviceType</code><br>
<em>
<a href="#airship.airshipit.org/v1.InfraService">
InfraService
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>optional</code><br>
<em>
<a href="#airship.airshipit.org/v1.OptsConfig">
OptsConfig
</a>
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>image</code><br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>nodelabels</code><br>
<em>
map[string]string
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>nodePort</code><br>
<em>
int
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>nodeInterfaceId</code><br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.InfraService">InfraService
(<code>string</code> alias)</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.InfraConfig">InfraConfig</a>)
</p>
<p>InfraService describes the type of infrastructure service that should be deployed when a sub-cluster is provisioned.</p>
<h3 id="airship.airshipit.org/v1.NodeSet">NodeSet
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.SIPClusterSpec">SIPClusterSpec</a>)
</p>
<p>NodeSet are the the list of Nodes objects workers,
or master that definee eexpectations
for the Tenant Clusters
Includes artifacts to associate with each defined namespace
Such as :
- Roles for the Nodes
- Flavor for theh Nodes image
- Scheduling expectations
- Scale of the group of Nodes</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>vm-flavor</code><br>
<em>
string
</em>
</td>
<td>
<p>VMFlavor is essentially a Flavor label identifying the
type of Node that meets the construction reqirements</p>
</td>
</tr>
<tr>
<td>
<code>spreadTopology</code><br>
<em>
<a href="#airship.airshipit.org/v1.SpreadTopology">
SpreadTopology
</a>
</em>
</td>
<td>
<p>PlaceHolder until we define the real expected
Implementation
Scheduling define constraints the allows the SIP Scheduler
to identify the required BMH&rsquo;s to allow CAPI to build a cluster</p>
</td>
</tr>
<tr>
<td>
<code>count</code><br>
<em>
<a href="#airship.airshipit.org/v1.VMCount">
VMCount
</a>
</em>
</td>
<td>
<p>Count defines the scale expectations for the Nodes</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.OptsConfig">OptsConfig
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.InfraConfig">InfraConfig</a>)
</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>sshkey</code><br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
<tr>
<td>
<code>clusterIP</code><br>
<em>
string
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.SIPCluster">SIPCluster
</h3>
<p>SIPCluster is the Schema for the sipclusters API</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>metadata</code><br>
<em>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta">
Kubernetes meta/v1.ObjectMeta
</a>
</em>
</td>
<td>
Refer to the Kubernetes API documentation for the fields of the
<code>metadata</code> field.
</td>
</tr>
<tr>
<td>
<code>spec</code><br>
<em>
<a href="#airship.airshipit.org/v1.SIPClusterSpec">
SIPClusterSpec
</a>
</em>
</td>
<td>
<br/>
<br/>
<table>
<tr>
<td>
<code>cluster-name</code><br>
<em>
string
</em>
</td>
<td>
<p>ClusterName is the name of the cluster to associate machines with</p>
</td>
</tr>
<tr>
<td>
<code>nodes</code><br>
<em>
<a href="#airship.airshipit.org/v1.NodeSet">
map[./pkg/api/v1.VMRoles]./pkg/api/v1.NodeSet
</a>
</em>
</td>
<td>
<p>Nodes are the list of Nodes objects workers, or master that definee eexpectations
of the Tenant cluster
VMRole is either Control or Workers
VMRole VMRoles <code>json:&quot;vm-role,omitempty&quot;</code></p>
</td>
</tr>
<tr>
<td>
<code>infra</code><br>
<em>
<a href="#airship.airshipit.org/v1.InfraConfig">
[]InfraConfig
</a>
</em>
</td>
<td>
<p>InfraServices is a list of services that are deployed when a SIPCluster is provisioned.</p>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<code>status</code><br>
<em>
<a href="#airship.airshipit.org/v1.SIPClusterStatus">
SIPClusterStatus
</a>
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.SIPClusterSpec">SIPClusterSpec
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.SIPCluster">SIPCluster</a>)
</p>
<p>SIPClusterSpec defines the desired state of a SIPCluster</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>cluster-name</code><br>
<em>
string
</em>
</td>
<td>
<p>ClusterName is the name of the cluster to associate machines with</p>
</td>
</tr>
<tr>
<td>
<code>nodes</code><br>
<em>
<a href="#airship.airshipit.org/v1.NodeSet">
map[./pkg/api/v1.VMRoles]./pkg/api/v1.NodeSet
</a>
</em>
</td>
<td>
<p>Nodes are the list of Nodes objects workers, or master that definee eexpectations
of the Tenant cluster
VMRole is either Control or Workers
VMRole VMRoles <code>json:&quot;vm-role,omitempty&quot;</code></p>
</td>
</tr>
<tr>
<td>
<code>infra</code><br>
<em>
<a href="#airship.airshipit.org/v1.InfraConfig">
[]InfraConfig
</a>
</em>
</td>
<td>
<p>InfraServices is a list of services that are deployed when a SIPCluster is provisioned.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.SIPClusterStatus">SIPClusterStatus
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.SIPCluster">SIPCluster</a>)
</p>
<p>SIPClusterStatus defines the observed state of SIPCluster</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>conditions</code><br>
<em>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#condition-v1-meta">
[]Kubernetes meta/v1.Condition
</a>
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.SpreadTopology">SpreadTopology
(<code>string</code> alias)</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.NodeSet">NodeSet</a>)
</p>
<h3 id="airship.airshipit.org/v1.VMCount">VMCount
</h3>
<p>
(<em>Appears on:</em>
<a href="#airship.airshipit.org/v1.NodeSet">NodeSet</a>)
</p>
<p>VMCount</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>active</code><br>
<em>
int
</em>
</td>
<td>
<p>INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
Important: Run &ldquo;make&rdquo; to regenerate code after modifying this file</p>
</td>
</tr>
<tr>
<td>
<code>standby</code><br>
<em>
int
</em>
</td>
<td>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h3 id="airship.airshipit.org/v1.VMRoles">VMRoles
(<code>string</code> alias)</h3>
<p>VMRoles defines the states the provisioner will report
the tenant has having.</p>
<div class="admonition note">
<p class="last">This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>
</div>

33
hack/api-docs/config.json Normal file
View File

@ -0,0 +1,33 @@
{
"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/apiextensions-apiserver/pkg/apis/apiextensions/v1\\.JSON$",
"docsURLTemplate": "https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1?tab=doc#JSON"
},
{
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
},
{
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Condition$",
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Condition"
}
],
"typeDisplayNamePrefixOverrides": {
"k8s.io/api/": "Kubernetes ",
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
"k8s.io/apiextensions-apiserver/": "Kubernetes "
},
"markdownDisabled": false
}

46
hack/api-docs/template/members.tpl Normal file
View File

@ -0,0 +1,46 @@
{{ define "members" }}
{{ range .Members }}
{{ if not (hiddenMember .)}}
<tr>
<td>
<code>{{ fieldName . }}</code><br>
<em>
{{ if linkForType .Type }}
<a href="{{ linkForType .Type }}">
{{ typeDisplayName .Type }}
</a>
{{ else }}
{{ typeDisplayName .Type }}
{{ end }}
</em>
</td>
<td>
{{ if fieldEmbedded . }}
<p>
(Members of <code>{{ fieldName . }}</code> are embedded into this type.)
</p>
{{ end}}
{{ if isOptionalMember .}}
<em>(Optional)</em>
{{ end }}
{{ safe (renderComments .CommentLines) }}
{{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
Refer to the Kubernetes API documentation for the fields of the
<code>metadata</code> field.
{{ end }}
{{ if or (eq (fieldName .) "spec") }}
<br/>
<br/>
<table>
{{ template "members" .Type }}
</table>
{{ end }}
</td>
</tr>
{{ end }}
{{ end }}
{{ end }}

46
hack/api-docs/template/pkg.tpl Normal file
View File

@ -0,0 +1,46 @@
{{ define "packages" }}
<h1>SIPCluster API reference</h1>
{{ with .packages}}
<p>Packages:</p>
<ul class="simple">
{{ range . }}
<li>
<a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
</li>
{{ end }}
</ul>
{{ end}}
{{ range .packages }}
<h2 id="{{- packageAnchorID . -}}">
{{- packageDisplayName . -}}
</h2>
{{ with (index .GoPackages 0 )}}
{{ with .DocComments }}
{{ safe (renderComments .) }}
{{ end }}
{{ end }}
Resource Types:
<ul class="simple">
{{- range (visibleTypes (sortedTypes .Types)) -}}
{{ if isExportedType . -}}
<li>
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
</li>
{{- end }}
{{- end -}}
</ul>
{{ range (visibleTypes (sortedTypes .Types))}}
{{ template "type" . }}
{{ end }}
{{ end }}
<div class="admonition note">
<p class="last">This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>
</div>
{{ end }}

60
hack/api-docs/template/type.tpl Normal file
View File

@ -0,0 +1,60 @@
{{ define "type" }}
<h3 id="{{ anchorIDForType . }}">
{{- .Name.Name }}
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
</h3>
{{ with (typeReferences .) }}
<p>
(<em>Appears on:</em>
{{- $prev := "" -}}
{{- range . -}}
{{- if $prev -}}, {{ end -}}
{{ $prev = . }}
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
{{- end -}}
)
</p>
{{ end }}
{{ with .CommentLines }}
{{ safe (renderComments .) }}
{{ end }}
{{ if .Members }}
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{{ if isExportedType . }}
<tr>
<td>
<code>apiVersion</code><br>
string</td>
<td>
<code>{{ apiGroup . }}</code>
</td>
</tr>
<tr>
<td>
<code>kind</code><br>
string
</td>
<td>
<code>{{ .Name.Name }}</code>
</td>
</tr>
{{ end }}
{{ template "members" . }}
</tbody>
</table>
</div>
</div>
{{ end }}
{{ end }}

20
pkg/api/v1/doc.go Normal file
View File

@ -0,0 +1,20 @@
/*
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 v1 contains API Schema definitions for the airship v1 API group
// +kubebuilder:object:generate=true
// +groupName=airship.airshipit.org
package v1

3
pkg/api/v1/groupversion_info.go
View File

@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
limitations under the License.
*/
// Package v1 contains API Schema definitions for the airship v1 API group
// +kubebuilder:object:generate=true
// +groupName=airship.airshipit.org
package v1
import (

2
tools/whitespace_linter
View File

@ -2,7 +2,7 @@
# git 1.9.0+ allows for exclusions in pathspecs via ':!foo' syntax.
# However, until git 2.13.0 there must be at least one "inclusive" pathspec, hence the './*'
trailing_whitespace=$(git grep -E -n -- ' +$' -- './*' ':!*.png')
trailing_whitespace=$(git grep -E -n -- ' +$' -- './*' ':!*.png' ':!docs/api/sipcluster.md')
if [[ -n "$trailing_whitespace" ]]; then
printf "ERROR: Trailing whitespaces:\n"