Skip to content

Commit ea60e1c

Browse files
chideatCopilot
chideat
and
Copilot
authored
Generate comprehensive documentation for ValkeyOperato (#48)
* Initial plan * feat: Generate comprehensive documentation for ValkeyOperato --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent 2316975 commit ea60e1c

25 files changed

+3211
-8
lines changed

‎Makefile‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -299,3 +299,31 @@ bundle-build: ## Build the bundle image.
299299
.PHONY: bundle-push
300300
bundle-push: ## Push the bundle image.
301301
$(MAKE) docker-push IMG=$(BUNDLE_IMG)
302+
303+
##@ Documentation
304+
305+
GEN_CRD_API_REFERENCE_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs
306+
307+
.PHONY: docs
308+
docs: gen-crd-api-reference-docs ## Generate documentation.
309+
@echo "Generating API documentation..."
310+
@mkdir -p docs/api
311+
@$(GEN_CRD_API_REFERENCE_DOCS) -config docs/config.json -api-dir ./api/v1alpha1 -out-file docs/api/v1alpha1-reference-generated.md || true
312+
@$(GEN_CRD_API_REFERENCE_DOCS) -config docs/config.json -api-dir ./api/rds/v1alpha1 -out-file docs/api/rds-v1alpha1-reference-generated.md || true
313+
@$(GEN_CRD_API_REFERENCE_DOCS) -config docs/config.json -api-dir ./api/core -out-file docs/api/core-reference-generated.md || true
314+
@go doc -all ./api/v1alpha1 > docs/api/v1alpha1-reference.md
315+
@go doc -all ./api/rds/v1alpha1 > docs/api/rds-v1alpha1-reference.md
316+
@go doc -all ./api/core > docs/api/core-reference.md
317+
@echo "Documentation generated in docs/ directory"
318+
319+
.PHONY: docs-serve
320+
docs-serve: gen-crd-api-reference-docs ## Serve documentation locally.
321+
@echo "Starting documentation server on http://localhost:8080"
322+
@$(GEN_CRD_API_REFERENCE_DOCS) -config docs/config.json -api-dir ./api -http-addr :8080 || \
323+
(echo "Falling back to simple HTTP server..."; cd docs && python3 -m http.server 8080)
324+
325+
.PHONY: gen-crd-api-reference-docs
326+
gen-crd-api-reference-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Download gen-crd-api-reference-docs locally if necessary.
327+
$(GEN_CRD_API_REFERENCE_DOCS): $(LOCALBIN)
328+
@test -s $(LOCALBIN)/gen-crd-api-reference-docs || \
329+
GOBIN=$(LOCALBIN) go install github.com/ahmetb/gen-crd-api-reference-docs@v0.3.0

‎README.md‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,20 @@
1818

1919
## Quickstart
2020

21-
If you have a Kubernetes cluster and `kubectl` configured to access it, run the following command to instance the operator:
21+
If you have a Kubernetes cluster and `kubectl` configured to access it, run the following commands to deploy the operator and create a simple cluster:
2222

23-
TODO
23+
```bash
24+
# Install the ValkeyOperator
25+
kubectl apply -k https://github.com/chideat/valkey-operator/config/default
26+
27+
# Deploy a simple Valkey cluster
28+
kubectl apply -f https://raw.githubusercontent.com/chideat/valkey-operator/main/docs/examples/basic/simple-cluster.yaml
29+
30+
# Check the cluster status
31+
kubectl get cluster simple-cluster -w
32+
```
33+
34+
For detailed installation and configuration instructions, see the [User Guide](./docs/guides/user-guide.md).
2435

2536
## Supported Versions
2637

@@ -35,14 +46,16 @@ TODO
3546

3647
## Documentation
3748

38-
ValkeyOperator is covered by following topics:
49+
ValkeyOperator is covered by comprehensive documentation:
50+
51+
* **[Operator Overview](./docs/guides/operator-overview.md)** - Architecture and core concepts
52+
* **[User Guide](./docs/guides/user-guide.md)** - Complete installation and usage guide
53+
* **[API Reference](./docs/api/index.md)** - Detailed API documentation
54+
* **[Examples](./docs/examples/)** - Ready-to-use configuration examples
3955

40-
* **TODO** Operator overview
41-
* **TODO** Deploying the operator
42-
* **TODO** Deploying a Valkey sentinel/cluster instance
43-
* **TODO** Monitoring the instance
56+
For a complete list of features and configuration options, see the [documentation directory](./docs/).
4457

45-
In addition, few [samples](./config/samples) can be find in this repo.
58+
In addition, practical [examples](./docs/examples) and [configuration samples](./config/samples) can be found in this repository.
4659

4760
## Contributing
4861

‎docs/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# This file ensures the docs directory is tracked by git

‎docs/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# ValkeyOperator Documentation
2+
3+
Welcome to the ValkeyOperator documentation. This guide will help you deploy, configure, and manage Valkey instances in Kubernetes using the ValkeyOperator.
4+
5+
## Quick Start
6+
7+
1. **[Operator Overview](./guides/operator-overview.md)** - Understanding ValkeyOperator architecture and capabilities
8+
2. **[User Guide](./guides/user-guide.md)** - Complete installation and usage guide
9+
3. **[Examples](./examples/)** - Ready-to-use configuration examples
10+
11+
## API Reference
12+
13+
- **[API Overview](./api/index.md)** - Complete API reference overview
14+
- **[Sentinel API](./api/v1alpha1-sentinel.md)** - Standalone sentinel configuration
15+
- **[User API](./api/v1alpha1-user.md)** - User and ACL management
16+
- **[Core Types](./api/core-types.md)** - Shared types and structures
17+
18+
## Unified Valkey Resource
19+
20+
ValkeyOperator uses a unified `Valkey` resource to manage all deployment architectures. You can specify the desired architecture using the `arch` field.
21+
22+
- `arch: replica` - Standalone Valkey instance.
23+
- `arch: cluster` - Valkey cluster with automatic sharding.
24+
- `arch: failover` - High-availability setup with Sentinel.
25+
26+
Here is an example of a Valkey cluster:
27+
```yaml
28+
apiVersion: rds.valkey.buf.red/v1alpha1
29+
kind: Valkey
30+
metadata:
31+
name: my-valkey-cluster
32+
spec:
33+
arch: cluster
34+
version: "8.0"
35+
replicas:
36+
shards: 3
37+
replicasOfShard: 1
38+
```
39+
40+
## Features
41+
42+
- ✅ **Unified API** - Manage all Valkey architectures with a single CRD.
43+
- ✅ **Multi-Architecture Support** - `replica`, `cluster`, and `failover` modes.
44+
- ✅ **High Availability** - Automatic failover and recovery.
45+
- ✅ **Horizontal Scaling** - Online scale up/down operations.
46+
- ✅ **Version Upgrades** - Graceful rolling updates.
47+
- ✅ **Persistent Storage** - Configurable storage with retention.
48+
- ✅ **Security** - TLS encryption and ACL support.
49+
- ✅ **Monitoring** - Built-in Prometheus exporter.
50+
- ✅ **IPv4/IPv6** - Dual-stack networking support.
51+
- ✅ **Node Scheduling** - Affinity, tolerations, node selectors.
52+
53+
## Supported Versions
54+
55+
| Valkey Version | Kubernetes | Status |
56+
|---------------|------------|---------|
57+
| 7.2.x | 1.31, 1.32 | ✅ Supported |
58+
| 8.0.x | 1.31, 1.32 | ✅ Supported |
59+
| 8.1.x | 1.31, 1.32 | ✅ Supported |
60+
61+
## Examples by Use Case
62+
63+
| Use Case | Example | Description |
64+
|----------|---------|-------------|
65+
| **Standalone** | [Valkey Standalone](./examples/basic/standalone.yaml) | Basic standalone Valkey instance |
66+
| **Cluster** | [Valkey Cluster](./examples/basic/cluster.yaml) | Valkey cluster with sharding |
67+
| **High Availability** | [Valkey Failover](./examples/basic/failover.yaml) | Sentinel-based failover |
68+
| **User Management** | [ACL Users](./examples/users/acl-users.yaml) | User and ACL configuration |
69+
| **Monitoring** | [With Monitoring](./examples/advanced/monitoring.yaml) | Prometheus integration |
70+
71+
## Quick Installation
72+
73+
```bash
74+
# Install the operator
75+
kubectl apply -k https://github.com/chideat/valkey-operator/config/default
76+
77+
# Deploy a standalone Valkey instance
78+
kubectl apply -f docs/examples/basic/standalone.yaml
79+
80+
# Check status
81+
kubectl get valkey valkey-standalone -w
82+
```
83+
84+
## Getting Help
85+
86+
- 📖 **Documentation**: You're reading it!
87+
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/chideat/valkey-operator/issues)
88+
- 💡 **Feature Requests**: [GitHub Issues](https://github.com/chideat/valkey-operator/issues)
89+
- 🤝 **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md)
90+
91+
## License
92+
93+
ValkeyOperator is licensed under the [Apache 2.0 License](../LICENSE).

‎docs/api/core-reference.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
package core // import "github.com/chideat/valkey-operator/api/core"
2+
3+
4+
TYPES
5+
6+
type AffinityPolicy string
7+
AffinityPolicy defines the affinity policy of the Valkey
8+
9+
const (
10+
// SoftAntiAffinity defines the soft anti-affinity policy
11+
// all pods will try to be scheduled on different nodes,
12+
// pods of the same shard may be scheduled on the same node
13+
SoftAntiAffinity AffinityPolicy = "SoftAntiAffinity"
14+
15+
// AntiAffinityInShard defines the anti-affinity policy in shard
16+
// pods of the same shard will be scheduled on different nodes,
17+
// but pods of different shards can be scheduled on the same node
18+
AntiAffinityInShard AffinityPolicy = "AntiAffinityInShard"
19+
20+
// AntiAffinity defines the anti-affinity policy
21+
// all pods will be scheduled on different nodes
22+
AntiAffinity AffinityPolicy = "AntiAffinity"
23+
24+
// CustomAffinity defines the custom affinity policy
25+
CustomAffinity AffinityPolicy = ""
26+
)
27+
type Arch string
28+
29+
const (
30+
// ValkeyCluster is the Valkey Cluster arch
31+
ValkeyCluster Arch = "cluster"
32+
// ValkeyFailover is the Valkey Sentinel arch, who relies on the sentinel to support high availability.
33+
ValkeyFailover Arch = "failover"
34+
// ValkeyReplica is the Valkey primary-replica arch, who use etcd to make sure the primary node.
35+
ValkeyReplica Arch = "replica"
36+
37+
// ValkeySentinel is the Sentinel arch
38+
ValkeySentinel Arch = "sentinel"
39+
)
40+
type Exporter struct {
41+
// Image the exporter image
42+
Image string `json:"image,omitempty"`
43+
// ImagePullPolicy
44+
ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`
45+
// Resources for setting resource requirements for the Pod Resources *v1.ResourceRequirements
46+
Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
47+
48+
// SecurityContext for setting security context for the Pod SecurityContext *corev1.SecurityContext
49+
SecurityContext *corev1.SecurityContext `json:"securityContext,omitempty"`
50+
}
51+
Exporter
52+
53+
func (in *Exporter) DeepCopy() *Exporter
54+
DeepCopy is an autogenerated deepcopy function, copying the receiver,
55+
creating a new Exporter.
56+
57+
func (in *Exporter) DeepCopyInto(out *Exporter)
58+
DeepCopyInto is an autogenerated deepcopy function, copying the receiver,
59+
writing into out. in must be non-nil.
60+
61+
type InstanceAccess struct {
62+
63+
// ServiceType defines the type of the all related services
64+
// +kubebuilder:default:=ClusterIP
65+
// +kubebuilder:validation:Enum=NodePort;LoadBalancer;ClusterIP
66+
ServiceType corev1.ServiceType `json:"serviceType,omitempty"`
67+
68+
// The annnotations of the service which will be attached to services
69+
Annotations map[string]string `json:"annotations,omitempty"`
70+
71+
// IPFamily represents the IP Family (IPv4 or IPv6).
72+
// This type is used to express the family of an IP expressed by a type (e.g. service.spec.ipFamilies).
73+
// +kubebuilder:validation:Enum=IPv4;IPv6
74+
IPFamilyPrefer corev1.IPFamily `json:"ipFamilyPrefer,omitempty"`
75+
76+
// Ports defines the nodeports of NodePort service
77+
// +kubebuilder:validation:Pattern="^([0-9]+:[0-9]+)(,[0-9]+:[0-9]+)*$"
78+
Ports string `json:"ports,omitempty"`
79+
80+
// EnableTLS enable TLS for external access
81+
EnableTLS bool `json:"enableTLS,omitempty"`
82+
83+
// Cert Issuer for external access TLS certificate
84+
CertIssuer string `json:"certIssuer,omitempty"`
85+
86+
// Cert Issuer Type for external access TLS certificate
87+
// +kubebuilder:default:="ClusterIssuer"
88+
// +kubebuilder:validation:Enum=ClusterIssuer;Issuer
89+
CertIssuerType string `json:"certIssuerType,omitempty"`
90+
}
91+
InstanceAccess
92+
93+
func (in *InstanceAccess) DeepCopy() *InstanceAccess
94+
DeepCopy is an autogenerated deepcopy function, copying the receiver,
95+
creating a new InstanceAccess.
96+
97+
func (in *InstanceAccess) DeepCopyInto(out *InstanceAccess)
98+
DeepCopyInto is an autogenerated deepcopy function, copying the receiver,
99+
writing into out. in must be non-nil.
100+
101+
type NodeRole string
102+
NodeRole valkey node role type
103+
104+
const (
105+
// NodeRoleNone None node role
106+
NodeRoleNone NodeRole = "none"
107+
// NodeRoleMaster Master node role
108+
// TODO: rename to Primary
109+
NodeRoleMaster NodeRole = "master"
110+
// NodeRoleReplica Master node role
111+
NodeRoleReplica NodeRole = "replica"
112+
// NodeRoleSentinel Master node role
113+
NodeRoleSentinel NodeRole = "sentinel"
114+
)
115+
type Storage struct {
116+
// The annnotations of the service which will be attached to services
117+
Annotations map[string]string `json:"annotations,omitempty"`
118+
119+
// storageClassName is the name of the StorageClass required by the claim.
120+
// if not set, the default StorageClass will be used
121+
// +optional
122+
StorageClassName *string `json:"storageClassName,omitempty"`
123+
124+
// Capacity is the cap of the volume to request.
125+
// if not set and StorageClassName is set, the default StorageClass size will be the double size of memory limit.
126+
Capacity *resource.Quantity `json:"capacity,omitempty"`
127+
128+
// AccessMode is the access mode of the volume.
129+
// +kubebuilder:default:=ReadWriteOnce
130+
AccessMode corev1.PersistentVolumeAccessMode `json:"accessMode,omitempty"`
131+
132+
// RetainAfterDeleted defines whether the storage should be retained after the ValkeyCluster is deleted
133+
RetainAfterDeleted bool `json:"retainAfterDeleted,omitempty"`
134+
}
135+
136+
func (in *Storage) DeepCopy() *Storage
137+
DeepCopy is an autogenerated deepcopy function, copying the receiver,
138+
creating a new Storage.
139+
140+
func (in *Storage) DeepCopyInto(out *Storage)
141+
DeepCopyInto is an autogenerated deepcopy function, copying the receiver,
142+
writing into out. in must be non-nil.
143+
144+
type ValkeyModule struct {
145+
// Path path of valkey module.
146+
//
147+
// .so suffix will be appended if path not suffixed provided
148+
// if path is a full path, the full path will be used else the module will be loaded from /usr/local/valkey/modules
149+
// +required
150+
Path string `json:"path"`
151+
152+
// Args args for module
153+
//
154+
// Supported for valkey 8.0+
155+
// +optional
156+
Args []string `json:"args,omitempty"`
157+
}
158+
ValkeyModule defines the module for Valkey
159+
160+
func (in *ValkeyModule) DeepCopy() *ValkeyModule
161+
DeepCopy is an autogenerated deepcopy function, copying the receiver,
162+
creating a new ValkeyModule.
163+
164+
func (in *ValkeyModule) DeepCopyInto(out *ValkeyModule)
165+
DeepCopyInto is an autogenerated deepcopy function, copying the receiver,
166+
writing into out. in must be non-nil.
167+
168+
type ValkeyNode struct {
169+
// ID is the valkey cluster node id, not runid
170+
ID string `json:"id,omitempty"`
171+
// ShardID cluster shard id of the node
172+
ShardID string `json:"shardId,omitempty"`
173+
// Role is the role of the node, master or slave
174+
Role NodeRole `json:"role"`
175+
// IP is the ip of the node. if access announce is enabled, it will be the access ip
176+
IP string `json:"ip"`
177+
// Port is the port of the node. if access announce is enabled, it will be the access port
178+
Port string `json:"port"`
179+
// Slots is the slot range for the shard, eg: 0-1000,1002,1005-1100
180+
Slots string `json:"slots,omitempty"`
181+
// MasterRef is the master node id of this node
182+
MasterRef string `json:"masterRef,omitempty"`
183+
// StatefulSet is the statefulset name of this pod
184+
StatefulSet string `json:"statefulSet"`
185+
// PodName current pod name
186+
PodName string `json:"podName"`
187+
// NodeName is the node name of the node where holds the pod
188+
NodeName string `json:"nodeName"`
189+
}
190+
ValkeyNode represent a ValkeyCluster Node
191+
192+
func (in *ValkeyNode) DeepCopy() *ValkeyNode
193+
DeepCopy is an autogenerated deepcopy function, copying the receiver,
194+
creating a new ValkeyNode.
195+
196+
func (in *ValkeyNode) DeepCopyInto(out *ValkeyNode)
197+
DeepCopyInto is an autogenerated deepcopy function, copying the receiver,
198+
writing into out. in must be non-nil.
199+

0 commit comments

Comments
 (0)