Skip to content

Commit c2f71b5

Browse files
NissesSenapNissesSenap
authored
Generate grafana crd documentation (#951)
* Add comments to the grafana types * Change api-docs to point to config/ This enables us to take the detailed documentation that is more detailed. controller-gen is smart and generates a shorter version due to the length of the crd due to etcd limits. * Use reviewdog directly Taken from https://github.com/chainguard-dev/actions/ * Ignore api.md
1 parent a942313 commit c2f71b5

File tree

6 files changed

+1630
-1474
lines changed

6 files changed

+1630
-1474
lines changed

‎.github/workflows/pr-validation.yaml

+70-5
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,77 @@ jobs:
1111
steps:
1212
- name: Clone the code
1313
uses: actions/checkout@755da8c3cf115ac066823e79a1e1788f8940201b #v3.2.0
14+
- name: reviewdog
15+
uses: reviewdog/action-setup@8f2ec89e6b467ca9175527d2a1641bbd0c05783b # v1.0.3
16+
with:
17+
reviewdog_version: latest
1418

15-
- name: trailing space
16-
uses: chainguard-dev/actions/trailing-space@main
17-
18-
- name: eof-check
19-
uses: chainguard-dev/actions/eof-newline@main
19+
- name: Trailing Whitespace
20+
shell: bash
21+
env:
22+
REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}
23+
run: |
24+
set -e
25+
pushd "${GITHUB_WORKSPACE}/" || exit 1
26+
echo '::group:: Flagging trailing whitespace with reviewdog 🐶 ...'
27+
# Don't fail because of grep
28+
set +o pipefail
29+
# Exclude generated and vendored files, plus some legacy
30+
# paths until we update all .gitattributes
31+
git ls-files |
32+
git check-attr --stdin linguist-generated | grep -Ev ': (set|true)$' | cut -d: -f1 |
33+
git check-attr --stdin linguist-vendored | grep -Ev ': (set|true)$' | cut -d: -f1 |
34+
git check-attr --stdin ignore-lint | grep -Ev ': (set|true)$' | cut -d: -f1 |
35+
grep -Ev '^(vendor/|third_party/|LICENSES/|.git|bundle/)' |
36+
grep -v api.md |
37+
xargs grep -nE " +$" |
38+
reviewdog -efm="%f:%l:%m" \
39+
-name="trailing whitespace" \
40+
-reporter="github-pr-check" \
41+
-filter-mode="added" \
42+
-fail-on-error="true" \
43+
-level="error"
44+
echo '::endgroup::'
45+
popd
46+
- name: EOF newline
47+
shell: bash
48+
env:
49+
REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}
50+
run: |
51+
set -e
52+
pushd "${GITHUB_WORKSPACE}/" || exit 1
53+
git status
54+
echo '::group:: Flagging missing EOF newlines with reviewdog 🐶 ...'
55+
# Don't fail because of misspell
56+
set +o pipefail
57+
# Lint exclude rule:
58+
# - nothing in vendor/
59+
# - nothing in third_party
60+
# - nothing in .git/
61+
# - no *.ai (Adobe Illustrator) files.
62+
LINT_FILES=$(git ls-files |
63+
git check-attr --stdin linguist-generated | grep -Ev ': (set|true)$' | cut -d: -f1 |
64+
git check-attr --stdin linguist-vendored | grep -Ev ': (set|true)$' | cut -d: -f1 |
65+
git check-attr --stdin ignore-lint | grep -Ev ': (set|true)$' | cut -d: -f1 |
66+
grep -Ev '^(vendor/|third_party/|LICENSES/|.git)' |
67+
grep -v '\.ai$' |
68+
grep -v '\.svg$')
69+
for x in $LINT_FILES; do
70+
# Based on https://stackoverflow.com/questions/34943632/linux-check-if-there-is-an-empty-line-at-the-end-of-a-file
71+
if [[ -f $x && ! ( -s "$x" && -z "$(tail -c 1 $x)" ) ]]; then
72+
# We add 1 to `wc -l` here because of this limitation (from the man page):
73+
# Characters beyond the final <newline> character will not be included in the line count.
74+
echo $x:$((1 + $(wc -l $x | tr -s ' ' | cut -d' ' -f 1))): Missing newline
75+
fi
76+
done |
77+
reviewdog -efm="%f:%l: %m" \
78+
-name="EOF Newline" \
79+
-reporter="github-pr-check" \
80+
-filter-mode="added" \
81+
-fail-on-error="true" \
82+
-level="error"
83+
echo '::endgroup::'
84+
popd
2085
2186
go-lint:
2287
runs-on: ubuntu-latest

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ api-docs: gen-crd-api-reference-docs kustomize
6262
@{ \
6363
set -e ;\
6464
TMP_DIR=$$(mktemp -d) ; \
65-
$(KUSTOMIZE) build config/crd -o $$TMP_DIR/crd-output.yaml ;\
65+
$(KUSTOMIZE) build config/ -o $$TMP_DIR/crd-output.yaml ;\
6666
$(API_REF_GEN) crdoc --resources $$TMP_DIR/crd-output.yaml --output docs/docs/api.md --template frontmatter.tmpl;\
6767
}
6868

‎api/v1beta1/grafana_types.go

+27-13
Original file line numberDiff line numberDiff line change
@@ -55,22 +55,35 @@ type OperatorReconcileVars struct {
5555
// GrafanaSpec defines the desired state of Grafana
5656
type GrafanaSpec struct {
5757
// +kubebuilder:pruning:PreserveUnknownFields
58-
Config map[string]map[string]string `json:"config,omitempty"`
59-
Ingress *IngressNetworkingV1 `json:"ingress,omitempty"`
60-
Route *RouteOpenshiftV1 `json:"route,omitempty"`
61-
Service *ServiceV1 `json:"service,omitempty"`
62-
Deployment *DeploymentV1 `json:"deployment,omitempty"`
63-
PersistentVolumeClaim *PersistentVolumeClaimV1 `json:"persistentVolumeClaim,omitempty"`
64-
ServiceAccount *ServiceAccountV1 `json:"serviceAccount,omitempty"`
65-
Client *GrafanaClient `json:"client,omitempty"`
66-
Jsonnet *JsonnetConfig `json:"jsonnet,omitempty"`
67-
External *External `json:"external,omitempty"`
58+
// Config defines how your grafana ini file should looks like.
59+
Config map[string]map[string]string `json:"config,omitempty"`
60+
// Ingress sets how the ingress object should look like with your grafana instance.
61+
Ingress *IngressNetworkingV1 `json:"ingress,omitempty"`
62+
// Route sets how the ingress object should look like with your grafana instance, this only works in Openshift.
63+
Route *RouteOpenshiftV1 `json:"route,omitempty"`
64+
// Service sets how the service object should look like with your grafana instance, contains a number of defaults.
65+
Service *ServiceV1 `json:"service,omitempty"`
66+
// Deployment sets how the deployment object should look like with your grafana instance, contains a number of defaults.
67+
Deployment *DeploymentV1 `json:"deployment,omitempty"`
68+
// PersistentVolumeClaim creates a PVC if you need to attach one to your grafana instance.
69+
PersistentVolumeClaim *PersistentVolumeClaimV1 `json:"persistentVolumeClaim,omitempty"`
70+
// ServiceAccount sets how the ServiceAccount object should look like with your grafana instance, contains a number of defaults.
71+
ServiceAccount *ServiceAccountV1 `json:"serviceAccount,omitempty"`
72+
// Client defines how the grafana-operator talks to the grafana instance.
73+
Client *GrafanaClient `json:"client,omitempty"`
74+
Jsonnet *JsonnetConfig `json:"jsonnet,omitempty"`
75+
// External enables you to configure external grafana instances that is not managed by the operator.
76+
External *External `json:"external,omitempty"`
6877
}
6978

7079
type External struct {
71-
URL string `json:"url"`
72-
ApiKey *v1.SecretKeySelector `json:"apiKey,omitempty"`
73-
AdminUser *v1.SecretKeySelector `json:"adminUser,omitempty"`
80+
// URL of the external grafana instance you want to manage.
81+
URL string `json:"url"`
82+
// The API key to talk to the external grafana instance, you need to define ether apiKey or adminUser/adminPassword.
83+
ApiKey *v1.SecretKeySelector `json:"apiKey,omitempty"`
84+
// AdminUser key to talk to the external grafana instance.
85+
AdminUser *v1.SecretKeySelector `json:"adminUser,omitempty"`
86+
// AdminPassword key to talk to the external grafana instance.
7487
AdminPassword *v1.SecretKeySelector `json:"adminPassword,omitempty"`
7588
}
7689

@@ -83,6 +96,7 @@ type GrafanaClient struct {
8396
// +nullable
8497
TimeoutSeconds *int `json:"timeout,omitempty"`
8598
// +nullable
99+
// If the operator should send it's request through the grafana instances ingress object instead of through the service.
86100
PreferIngress *bool `json:"preferIngress,omitempty"`
87101
}
88102

‎config/grafana.integreatly.org_grafanas.yaml

+28-4
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,13 @@ spec:
3636
description: GrafanaSpec defines the desired state of Grafana
3737
properties:
3838
client:
39-
description: GrafanaClient contains the Grafana API client settings
39+
description: Client defines how the grafana-operator talks to the
40+
grafana instance.
4041
properties:
4142
preferIngress:
43+
description: If the operator should send it's request through
44+
the grafana instances ingress object instead of through the
45+
service.
4246
nullable: true
4347
type: boolean
4448
timeout:
@@ -50,9 +54,13 @@ spec:
5054
additionalProperties:
5155
type: string
5256
type: object
57+
description: Config defines how your grafana ini file should looks
58+
like.
5359
type: object
5460
x-kubernetes-preserve-unknown-fields: true
5561
deployment:
62+
description: Deployment sets how the deployment object should look
63+
like with your grafana instance, contains a number of defaults.
5664
properties:
5765
metadata:
5866
description: ObjectMeta contains only a [subset of the fields
@@ -8112,9 +8120,12 @@ spec:
81128120
type: object
81138121
type: object
81148122
external:
8123+
description: External enables you to configure external grafana instances
8124+
that is not managed by the operator.
81158125
properties:
81168126
adminPassword:
8117-
description: SecretKeySelector selects a key of a Secret.
8127+
description: AdminPassword key to talk to the external grafana
8128+
instance.
81188129
properties:
81198130
key:
81208131
description: The key of the secret to select from. Must be
@@ -8133,7 +8144,7 @@ spec:
81338144
type: object
81348145
x-kubernetes-map-type: atomic
81358146
adminUser:
8136-
description: SecretKeySelector selects a key of a Secret.
8147+
description: AdminUser key to talk to the external grafana instance.
81378148
properties:
81388149
key:
81398150
description: The key of the secret to select from. Must be
@@ -8152,7 +8163,8 @@ spec:
81528163
type: object
81538164
x-kubernetes-map-type: atomic
81548165
apiKey:
8155-
description: SecretKeySelector selects a key of a Secret.
8166+
description: The API key to talk to the external grafana instance,
8167+
you need to define ether apiKey or adminUser/adminPassword.
81568168
properties:
81578169
key:
81588170
description: The key of the secret to select from. Must be
@@ -8171,11 +8183,15 @@ spec:
81718183
type: object
81728184
x-kubernetes-map-type: atomic
81738185
url:
8186+
description: URL of the external grafana instance you want to
8187+
manage.
81748188
type: string
81758189
required:
81768190
- url
81778191
type: object
81788192
ingress:
8193+
description: Ingress sets how the ingress object should look like
8194+
with your grafana instance.
81798195
properties:
81808196
metadata:
81818197
description: ObjectMeta contains only a [subset of the fields
@@ -8524,6 +8540,8 @@ spec:
85248540
x-kubernetes-map-type: atomic
85258541
type: object
85268542
persistentVolumeClaim:
8543+
description: PersistentVolumeClaim creates a PVC if you need to attach
8544+
one to your grafana instance.
85278545
properties:
85288546
metadata:
85298547
description: ObjectMeta contains only a [subset of the fields
@@ -8678,6 +8696,8 @@ spec:
86788696
type: object
86798697
type: object
86808698
route:
8699+
description: Route sets how the ingress object should look like with
8700+
your grafana instance, this only works in Openshift.
86818701
properties:
86828702
metadata:
86838703
description: ObjectMeta contains only a [subset of the fields
@@ -8814,6 +8834,8 @@ spec:
88148834
type: object
88158835
type: object
88168836
service:
8837+
description: Service sets how the service object should look like
8838+
with your grafana instance, contains a number of defaults.
88178839
properties:
88188840
metadata:
88198841
description: ObjectMeta contains only a [subset of the fields
@@ -9163,6 +9185,8 @@ spec:
91639185
type: object
91649186
type: object
91659187
serviceAccount:
9188+
description: ServiceAccount sets how the ServiceAccount object should
9189+
look like with your grafana instance, contains a number of defaults.
91669190
properties:
91679191
automountServiceAccountToken:
91689192
type: boolean

‎config/kustomization.yaml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# This kustomization.yaml is not intended to be run by itself,
2+
# It's only mean for documentation generation.
3+
# If you want to install the operator CRD us `make install` and it will use the files under crd/base
4+
resources:
5+
- grafana.integreatly.org_grafanas.yaml
6+
- grafana.integreatly.org_grafanadashboards.yaml
7+
- grafana.integreatly.org_grafanadatasources.yaml
8+
- grafana.integreatly.org_grafanafolders.yaml
9+
#+kubebuilder:scaffold:crdkustomizeresource

0 commit comments

Comments
 (0)