Skip to content

Commit 48fb1cf

Browse files
kenfinnigankenfinnigan
committed
Add documentation
1 parent af2e5fd commit 48fb1cf

File tree

4 files changed

+221
-0
lines changed

4 files changed

+221
-0
lines changed

‎BUNDLE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# OperatorHub.io Bundles
2+
3+
This document contains information on how to update and release new versions of the operator
4+
that will be made available in OperatorHub through OLM.
5+
6+
## Process to release a bundle
7+
8+
1. Fork and clone the [OperatorHub.io](https://github.com/k8s-operatorhub/community-operators) repository
9+
2. Navigate to _/operators/application-services-metering-operator_
10+
3. Copy the previous version directory and paste it to the same place with a name for the new version
11+
4. Update the version across all files in the directory
12+
5. After `spec`.`version`, update the `replaces` key (or add if first update) with the version of the operator that will be replaceable with this update.
13+
6. Update the operator deployment in the CSV, or other manifest files, as needed based on any changes in the released Kubernetes.yml files of the operator release.
14+
7. Following the [verification instructions](VERIFICATION.md#operatorhub) to ensure nothing is obviously broken.
15+
8. If the descriptions were updated, ensure they look ok with the [preview tool](https://operatorhub.io/preview).
16+
9. Open a PR against the repo, following the PR checklist.
17+
18+
Additional documentation on this process can be found [here](https://k8s-operatorhub.github.io/community-operators/).
19+
20+
Once this PR is merged, do the same for the [OperatorHub packaged in OpenShift and OKD](https://github.com/redhat-openshift-ecosystem/community-operators-prod) repository.

‎README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Application Services Metering operator
2+
3+
The purpose of this operator is to provide the necessary metrics to calculate utilization of Application Services products.
4+
5+
Any product with the following labels will be measured:
6+
7+
- `rht.prod_name`
8+
- `rht.prod_ver`
9+
- `rht.comp`
10+
- `rht.comp_ver`
11+
- `rht.subcomp`
12+
- `rht.subcomp_t`
13+
14+
The operator will produce a metric named `appsvcs_cpu_usage_cores` that has a label of `prod_name`.
15+
The possible values for `prod_name` are:
16+
17+
- Red_Hat_Integration
18+
- Red_Hat_Process_Automation
19+
- Red_Hat_Runtimes
20+
21+
NOTE: A future version of the operator will not aggregate each product instance into Runtimes,
22+
Integration, or Process Automation,
23+
but provide a metric/label combination based on the full set of labels on the pod.
24+
25+
## Related documents
26+
27+
- [Operator release process](RELEASE.md)
28+
- [Operator verification](VERIFICATION.md)
29+
- [Operator bundle process](BUNDLE.md)

‎RELEASE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Operator release process
2+
3+
1. Go to the "Operator release" GH Action [page](https://github.com/redhat-developer/application-services-metering-operator/actions/workflows/release.yml)
4+
2. Click the "Run workflow" drop down
5+
3. Enter a release/tag version and the next development version with `-SNAPSHOT` suffix
6+
4. Click "Run workflow" button to perform the release
7+
8+
The release process will do the following:
9+
10+
- Tag the code with the desired version
11+
- Update the `main` branch to the new development version
12+
- Push the built Docker image to the operator [repository](https://quay.io/repository/redhat-developer/application-services-metering-operator) on quay.io

‎VERIFICATION.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Operator verification process
2+
3+
There are two different verifications available, depending on what is being verified:
4+
5+
1. The [cluster deployment](#cluster-deployment) approach utilizes a built image, but without the OLM configuration of the [OperatorHub](#operatorhub) approach.
6+
2. The [OperatorHub](#operatorhub) way enables the validation of OperatorHub bundle configuration with an OpenShift environment. This includes all the necessary config for integration with OLM (Operator Lifecycle Manager).
7+
8+
## Cluster deployment
9+
10+
This will deploy an image of the operator into a Kubernetes/OpenShift cluster.
11+
12+
```shell script
13+
docker login quay.io
14+
```
15+
16+
Make and push a Docker image of the operator:
17+
18+
```shell script
19+
make docker-build docker-push IMG=quay.io/{user}/application-services-operator:{version}
20+
```
21+
22+
Utilize the operator make commands to install the CRD and deploy the operator:
23+
24+
```shell script
25+
make install
26+
make deploy
27+
cat <<EOF | kubectl apply -f -
28+
apiVersion: rbac.authorization.k8s.io/v1
29+
kind: ClusterRoleBinding
30+
metadata:
31+
name: application-services-metering-operator-admin
32+
subjects:
33+
- kind: ServiceAccount
34+
name: application-services-metering-operator
35+
namespace: default
36+
roleRef:
37+
kind: ClusterRole
38+
name: cluster-admin
39+
apiGroup: ""
40+
EOF
41+
```
42+
43+
Verify the operator is running:
44+
45+
```shell script
46+
kubectl get all
47+
```
48+
49+
Install a Meter custom resource to commence metering:
50+
51+
```shell script
52+
cat <<EOF | kubectl apply -f -
53+
apiVersion: applicationservices.redhat.com/v1
54+
kind: Meter
55+
metadata:
56+
name: application-services-metering-operator
57+
spec:
58+
includeInfrastructure: true
59+
meterCollectionEnabled: true
60+
EOF
61+
```
62+
63+
## OperatorHub
64+
65+
There are two repositories that can be used for verifying a new operator release:
66+
67+
- [OperatorHub.io](https://github.com/k8s-operatorhub/community-operators/tree/main/operators)
68+
- [OperatorHub packaged in OpenShift and OKD](https://github.com/redhat-openshift-ecosystem/community-operators-prod)
69+
70+
One of these git repositories will be required to validate the operator through the OperatorHub.
71+
72+
### Requirements
73+
74+
- Podman running
75+
- For macOS, `podman machine init` and then `podman machine start`
76+
- [OPM](https://github.com/operator-framework/operator-registry/releases/latest) installed and available on path
77+
78+
### Validate Operator Bundle
79+
80+
From within a version directory under /operators/application-services-metering-operator, run:
81+
82+
```shell-script
83+
operator-sdk bundle validate --select-optional name=operatorhub .
84+
```
85+
86+
This command provides details on any errors in the operator manifests that need resolution.
87+
At the current time, the following messages are expected and don't cause an issue:
88+
89+
```shell-script
90+
ERRO[0000] Error: Value application-services-metering-operator: invalid service account found in bundle. sa name cannot match service account defined for deployment spec in CSV
91+
ERRO[0000] Error: Value application-services-metering-operator: invalid service account found in bundle. sa name cannot match service account defined for deployment spec in CSV
92+
WARN[0000] Warning: Value : (application-services-metering-operator.v0.6.0) csv.Spec.minKubeVersion is not informed. It is recommended you provide this information. Otherwise, it would mean that your operator project can be distributed and installed in any cluster version available, which is not necessarily the case for all projects.
93+
```
94+
95+
### Publish operator metadata to a catalog
96+
97+
From the /operators/application-services-metering-operator directory:
98+
99+
```shell-script
100+
podman build -f {version}/Dockerfile -t application-services-metering-operator:v{version} {version}/
101+
podman push application-services-metering-operator:v{version} quay.io/{user}/application-services-metering-operator:v{version}
102+
```
103+
104+
Where `{version}` should be replaced with the version matching the bundle directory name for the version being tested.
105+
106+
Login in to quay.io:
107+
108+
```shell-script
109+
podman login quay.io
110+
```
111+
112+
Package an OperatorHub catalog that includes the version of the operator to be verified:
113+
114+
```shell-script
115+
opm index add --bundles quay.io/{user}/application-services-metering-operator:v{version} --from-index quay.io/operatorhubio/catalog:latest --tag quay.io/{user}/my-test-catalog:latest
116+
```
117+
118+
NOTE: Need to run `podman login quay.io` before each use of `opm index`!
119+
120+
```shell-script
121+
podman push quay.io/{user}/my-test-catalog:latest
122+
```
123+
124+
### Create CatalogSource for Marketplace
125+
126+
We need to update the OperatorHub catalog in the OpenShift instance used for testing.
127+
Once logged in with `oc login`, run:
128+
129+
```shell-script
130+
cat <<EOF | kubectl apply -f -
131+
apiVersion: operators.coreos.com/v1alpha1
132+
kind: CatalogSource
133+
metadata:
134+
name: my-test-catalog
135+
namespace: openshift-marketplace
136+
spec:
137+
sourceType: grpc
138+
image: quay.io/{user}/my-test-catalog:latest
139+
EOF
140+
```
141+
142+
Allow about 10s after success before accessing the OperatorHub to ensure it's been reloaded.
143+
144+
### Install operator from OperatorHub
145+
146+
Open OperatorHub and search for "meter" to find the operator.
147+
Select it, verify the version available is the one added to the temporary catalog,
148+
and click "Install".
149+
150+
Once installed, open the operator view and click "Meter" and "Create Meter".
151+
152+
Be sure to select "includeInfrastructure" if you want to measure infrastructure components as well as application ones.
153+
154+
## View metrics from operator
155+
156+
Click on "Monitoring" and then "Metrics" in the left hand menu of the OpenShift Console.
157+
In the search field, start typing `appsvcs_cpu_usage_cores` or `appsvcs_cores_by_product:sum`,
158+
select the desired metric, and then run the query.
159+
160+
If workloads are running that utilize the required labels, they will be aggregated under one of the three Application Services product areas: Runtimes, Integration, and Process Automation.

0 commit comments

Comments
 (0)