Skip to content

Commit 1264baa

Browse files
leomiraandaleomiraanda
committed
feat: add more docs
1 parent 2a46149 commit 1264baa

3 files changed

Lines changed: 99 additions & 55 deletions

File tree

‎suse-ai-operator/README.md‎

Lines changed: 98 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,86 @@
1-
# suse-ai-operator
2-
// TODO(user): Add simple overview of use/purpose
1+
# SUSE AI Operator
2+
The SUSE AI Extension Operator installs and manages Rancher UI extension for SUSE AI using a declarative Kubernetes Custom Resource (CR). It acts as a bridge between Helm-based extension packaging and Rancher UIPlugin resources, handling lifecycle, validation, retries, and cleanup in a Kubernetes-native way.
33

4-
## Description
5-
// TODO(user): An in-depth paragraph about your project and overview of use
4+
## Purpose
5+
This operator exists to:
6+
- Install SUSE AI Rancher UI extensions safely and declaratively.
7+
- Prevent conflicts with operator-unmanaged Helm resources.
8+
- Manage Helm releases, ClusterRepos, and UIPlugins.
69

710
## Getting Started
811

912
### Prerequisites
10-
- go version v1.24.0+
11-
- docker version 17.03+.
12-
- kubectl version v1.11.3+.
13-
- Access to a Kubernetes v1.11.3+ cluster.
13+
- go v1.24.0+
14+
- docker v17.03+
15+
- kubectl v1.11.3+
16+
- Access to a Kubernetes v1.11.3+ cluster
17+
- Helm 3.x
18+
- Rancher installed (for UIPlugin and ClusterRepo integration)
1419

15-
### To Deploy on the cluster
20+
The following CRDs must exist before adding the operator:
21+
- `uiplugins.catalog.cattle.io`
22+
- `clusterrepos.catalog.cattle.io`
23+
24+
### Installation
25+
26+
The operator is distributed as a Helm chart and installs:
27+
- Controller Deployment
28+
- RBAC
29+
- CRDs
30+
- Metrics Service
31+
32+
1. **Install the SUSE AI Operator.** First, install the operator via Helm:
33+
34+
```sh
35+
helm install suse-ai-operator \
36+
-n suse-ai-operator-system \
37+
--create-namespace \
38+
oci://ghcr.io/suse/chart/suse-ai-operator
39+
```
40+
41+
This will deploy the SUSE AI Operator into the `suse-ai-operator-system` namespace.
42+
43+
2. **Create the InstallAIExtension CR.** Once the operator is installed, apply the InstallAIExtension Custom Resource (CR) to install the required extension. Below is an example of the `extension.yaml`:
44+
```yaml
45+
apiVersion: ai-platform.suse.com/v1alpha1
46+
kind: InstallAIExtension
47+
metadata:
48+
name: suseai
49+
spec:
50+
helm:
51+
name: suse-ai-lifecycle-manager
52+
url: "ghcr.io/suse/chart/suse-ai-lifecycle-manager"
53+
version: "1.0.0"
54+
type: "oci"
55+
extension:
56+
name: suse-ai-lifecycle-manager
57+
version: "1.0.0"
58+
```
59+
Apply this file
60+
```sh
61+
kubectl apply -f extension.yaml
62+
```
63+
64+
### Uninstall
65+
66+
1. **Remove the InstallAIExtension CR.** To remove the InstallAIExtension CR, use:
67+
```sh
68+
kubectl delete -f extension.yaml
69+
```
70+
71+
2. **Uninstall the SUSE AI Operator.** To uninstall the operator, run the following command:
72+
```sh
73+
helm uninstall suse-ai-operator -n suse-ai-operator-system
74+
```
75+
76+
3. **Delete the CRDs.** After uninstalling the operator, you remove the associated Custom Resource Definitions (CRDs). To delete the InstallAIExtension CRD, use:
77+
```sh
78+
kubectl delete crd installaiextension.ai-platform.suse.com
79+
```
80+
81+
## Development
82+
83+
### To Build and Test locally
1684
**Build and push your image to the location specified by `IMG`:**
1785

1886
```sh
@@ -38,7 +106,7 @@ make deploy IMG=<some-registry>/suse-ai-operator:tag
38106
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
39107
privileges or be logged in as admin.
40108

41-
**Create instances of your solution**
109+
**Create CRs**
42110
You can apply the samples (examples) from the config/sample:
43111

44112
```sh
@@ -66,51 +134,35 @@ make uninstall
66134
make undeploy
67135
```
68136

69-
## Project Distribution
70-
71-
Following the options to release and provide this solution to the users.
137+
## Testing
72138

73-
### By providing a bundle with all YAML files
139+
1. **Install Rancher (or mock CRDs)**
74140

75-
1. Build the installer for the image built and published in the registry:
141+
2. **Install the operator:**
76142

77-
```sh
78-
make build-installer IMG=<some-registry>/suse-ai-operator:tag
143+
```bash
144+
helm install suse-ai-operator ./charts/suse-ai-operator -n suse-ai-operator-system
79145
```
80146

81-
**NOTE:** The makefile target mentioned above generates an 'install.yaml'
82-
file in the dist directory. This file contains all the resources built
83-
with Kustomize, which are necessary to install this project without its
84-
dependencies.
85-
86-
2. Using the installer
87-
88-
Users can just run 'kubectl apply -f <URL for YAML BUNDLE>' to install
89-
the project, i.e.:
90-
91-
```sh
92-
kubectl apply -f https://raw.githubusercontent.com/<org>/suse-ai-operator/<tag or branch>/dist/install.yaml
147+
3. **Apply an extension:**
148+
```bash
149+
kubectl apply -f config/samples/installaiextension.yaml
93150
```
94151

95-
### By providing a Helm Chart
96-
97-
1. Build the chart using the optional helm plugin
98-
99-
```sh
100-
kubebuilder edit --plugins=helm/v1-alpha
152+
4. **Observe reconciliation:**
153+
```bash
154+
kubectl logs -l app.kubernetes.io/name=suse-ai-operator -f -n suse-ai-operator-system
101155
```
102156

103-
2. See that a chart was generated under 'dist/chart', and users
104-
can obtain this solution from there.
105-
106-
**NOTE:** If you change the project, you need to update the Helm Chart
107-
using the same command above to sync the latest changes. Furthermore,
108-
if you create webhooks, you need to use the above command with
109-
the '--force' flag and manually ensure that any custom configuration
110-
previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml'
111-
is manually re-applied afterwards.
157+
5. **Verify resources:**
158+
```bash
159+
kubectl get installaiextensions
160+
kubectl get uiplugins -A
161+
kubectl get clusterrepos
162+
helm list -A
163+
```
112164

113-
## Doing
165+
<!-- ## Doing
114166
- [ ] change extension from gh-pages branch to container (pipeline)
115167
- [ ] change operator to install container
116168
- [ ] helm chart for the operator
@@ -121,15 +173,7 @@ is manually re-applied afterwards.
121173
122174
## Tests
123175
- [ ] No crds available (uiplugin/clusterrepo)
124-
- [ ] Plugin/extension wrong name
125-
126-
127-
## Contributing
128-
// TODO(user): Add detailed information on how you would like others to contribute to this project
129-
130-
**NOTE:** Run `make help` for more information on all potential `make` targets
131-
132-
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
176+
- [ ] Plugin/extension wrong name -->
133177

134178
## License
135179

suse-ai-operator/config/samples/ai-platform_v1alpha1_installaiextension.yaml renamed to suse-ai-operator/config/samples/installaiextension.yaml

File renamed without changes.

‎suse-ai-operator/config/samples/kustomization.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
## Append samples of your project ##
22
resources:
3-
- ai-platform_v1alpha1_installaiextension.yaml
3+
- installaiextension.yaml
44
# +kubebuilder:scaffold:manifestskustomizesamples

0 commit comments

Comments
 (0)