|
| 1 | +--- |
| 2 | +title: Go Types |
| 3 | +description: Programmatic management of Cozystack resources using Go types |
| 4 | +weight: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +## Go Types |
| 8 | + |
| 9 | +Cozystack publishes its Kubernetes resource types as a Go module, enabling management of Cozystack resources from any Go code. The types are available at [pkg.go.dev/github.com/cozystack/cozystack/api/apps/v1alpha1](https://pkg.go.dev/github.com/cozystack/cozystack/api/apps/v1alpha1). |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +Add the dependency to your Go module: |
| 14 | + |
| 15 | +```bash |
| 16 | +go get github.com/cozystack/cozystack/api/apps/v1alpha1@v1.2.0 |
| 17 | +``` |
| 18 | + |
| 19 | +## Use Cases |
| 20 | + |
| 21 | +The Go types are useful for: |
| 22 | + |
| 23 | +- **Building custom automation tools** - Create scripts or applications that programmatically deploy and manage Cozystack resources |
| 24 | +- **Integrating with external systems** - Connect Cozystack with your own CI/CD pipelines, monitoring systems, or orchestration tools |
| 25 | +- **Validating configurations** - Use the types to validate resource specifications before applying them to the cluster |
| 26 | +- **Generating documentation** - Parse and analyze existing Cozystack resources |
| 27 | +- **Building dashboards** - Create custom UIs for Cozystack management |
| 28 | + |
| 29 | +## Available Packages |
| 30 | + |
| 31 | +The module contains packages for each resource type, you can explore it for your specific version in [pkg.go.dev/github.com/cozystack/cozystack/api/apps/v1alpha1](https://pkg.go.dev/github.com/cozystack/cozystack/api/apps/v1alpha1) |
| 32 | + |
| 33 | +### Simple Example |
| 34 | + |
| 35 | +For basic usage, importing a specific package is straightforward: |
| 36 | + |
| 37 | +```go |
| 38 | +package main |
| 39 | + |
| 40 | +import ( |
| 41 | + "fmt" |
| 42 | + |
| 43 | + "github.com/cozystack/cozystack/api/apps/v1alpha1/vmdisk" |
| 44 | +) |
| 45 | + |
| 46 | +func main() { |
| 47 | + // Create a VMDisk source from a named image |
| 48 | + image := vmdisk.SourceImage{Name: "ubuntu"} |
| 49 | + fmt.Printf("Source: %+v\n", image) |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +## Complex Example |
| 54 | + |
| 55 | +This example demonstrates creating and marshaling several Cozystack resource types: |
| 56 | + |
| 57 | +```go |
| 58 | +package main |
| 59 | + |
| 60 | +import ( |
| 61 | + "encoding/json" |
| 62 | + "fmt" |
| 63 | + |
| 64 | + "github.com/cozystack/cozystack/api/apps/v1alpha1/postgresql" |
| 65 | + "github.com/cozystack/cozystack/api/apps/v1alpha1/vminstance" |
| 66 | + "github.com/cozystack/cozystack/api/apps/v1alpha1/redis" |
| 67 | + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" |
| 68 | + "k8s.io/apimachinery/pkg/api/resource" |
| 69 | +) |
| 70 | + |
| 71 | +func main() { |
| 72 | + // Create a PostgreSQL config with users and databases |
| 73 | + pgConfig := postgresql.Config{ |
| 74 | + TypeMeta: metav1.TypeMeta{ |
| 75 | + APIVersion: "apps.cozystack.io/v1alpha1", |
| 76 | + Kind: "Postgres", |
| 77 | + }, |
| 78 | + ObjectMeta: metav1.ObjectMeta{ |
| 79 | + Name: "my-app-db", |
| 80 | + Namespace: "tenant-myapp", |
| 81 | + }, |
| 82 | + Spec: postgresql.ConfigSpec{ |
| 83 | + Replicas: 3, |
| 84 | + Size: resource.MustParse("50Gi"), |
| 85 | + Version: postgresql.Version("v18"), |
| 86 | + Users: map[string]postgresql.User{ |
| 87 | + "appuser": { |
| 88 | + Password: "secretpassword", |
| 89 | + Replication: false, |
| 90 | + }, |
| 91 | + "readonly": { |
| 92 | + Password: "readonlypass", |
| 93 | + }, |
| 94 | + }, |
| 95 | + Databases: map[string]postgresql.Database{ |
| 96 | + "myapp": { |
| 97 | + Extensions: []string{"pg_trgm", "uuid-ossp"}, |
| 98 | + Roles: postgresql.DatabaseRoles{ |
| 99 | + Admin: []string{"appuser"}, |
| 100 | + Readonly: []string{"readonly"}, |
| 101 | + }, |
| 102 | + }, |
| 103 | + }, |
| 104 | + Backup: postgresql.Backup{ |
| 105 | + Enabled: true, |
| 106 | + DestinationPath: "s3://mybackups/postgres/", |
| 107 | + EndpointURL: "http://minio:9000", |
| 108 | + RetentionPolicy: "30d", |
| 109 | + S3AccessKey: "myaccesskey", |
| 110 | + S3SecretKey: "mysecretkey", |
| 111 | + Schedule: "0 2 * * * *", |
| 112 | + }, |
| 113 | + Quorum: postgresql.Quorum{ |
| 114 | + MinSyncReplicas: 1, |
| 115 | + MaxSyncReplicas: 1, |
| 116 | + }, |
| 117 | + Postgresql: postgresql.PostgreSQL{ |
| 118 | + Parameters: postgresql.PostgreSQLParameters{ |
| 119 | + MaxConnections: 200, |
| 120 | + }, |
| 121 | + }, |
| 122 | + }, |
| 123 | + } |
| 124 | + |
| 125 | + // Marshal to JSON for kubectl apply |
| 126 | + pgJSON, _ := json.MarshalIndent(pgConfig, "", " ") |
| 127 | + fmt.Println(string(pgJSON)) |
| 128 | + |
| 129 | + // Create a Redis config |
| 130 | + redisConfig := redis.Config{ |
| 131 | + TypeMeta: metav1.TypeMeta{ |
| 132 | + APIVersion: "apps.cozystack.io/v1alpha1", |
| 133 | + Kind: "Redis", |
| 134 | + }, |
| 135 | + ObjectMeta: metav1.ObjectMeta{ |
| 136 | + Name: "cache", |
| 137 | + Namespace: "tenant-myapp", |
| 138 | + }, |
| 139 | + Spec: redis.ConfigSpec{ |
| 140 | + Replicas: 2, |
| 141 | + Size: resource.MustParse("5Gi"), |
| 142 | + Version: redis.Version("v8"), |
| 143 | + AuthEnabled: true, |
| 144 | + ResourcesPreset: redis.ResourcesPreset("medium"), |
| 145 | + }, |
| 146 | + } |
| 147 | + |
| 148 | + // Create a VMInstance with disks |
| 149 | + vmConfig := vminstance.Config{ |
| 150 | + TypeMeta: metav1.TypeMeta{ |
| 151 | + APIVersion: "apps.cozystack.io/v1alpha1", |
| 152 | + Kind: "VMInstance", |
| 153 | + }, |
| 154 | + ObjectMeta: metav1.ObjectMeta{ |
| 155 | + Name: "my-vm", |
| 156 | + Namespace: "tenant-myapp", |
| 157 | + }, |
| 158 | + Spec: vminstance.ConfigSpec{ |
| 159 | + InstanceType: "u1.medium", |
| 160 | + InstanceProfile: "ubuntu", |
| 161 | + RunStrategy: vminstance.RunStrategy("Always"), |
| 162 | + External: true, |
| 163 | + ExternalMethod: vminstance.ExternalMethod("PortList"), |
| 164 | + ExternalPorts: []int{22, 80, 443}, |
| 165 | + Resources: vminstance.Resources{ |
| 166 | + Cpu: resource.MustParse("2"), |
| 167 | + Memory: resource.MustParse("4Gi"), |
| 168 | + Sockets: resource.MustParse("1"), |
| 169 | + }, |
| 170 | + Disks: []vminstance.Disk{ |
| 171 | + {Bus: "sata", Name: "rootdisk"}, |
| 172 | + {Bus: "sata", Name: "datadisk"}, |
| 173 | + }, |
| 174 | + Subnets: []vminstance.Subnet{ |
| 175 | + {Name: "default"}, |
| 176 | + }, |
| 177 | + SshKeys: []string{ |
| 178 | + "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...", |
| 179 | + }, |
| 180 | + CloudInit: `#cloud-config |
| 181 | +packages: |
| 182 | + - nginx`, |
| 183 | + }, |
| 184 | + } |
| 185 | +} |
| 186 | +``` |
| 187 | + |
| 188 | +## Deploying Resources |
| 189 | + |
| 190 | +After creating your resource configurations, you can deploy them using: |
| 191 | + |
| 192 | +1. **kubectl** - Marshal to YAML and apply: |
| 193 | + ```go |
| 194 | + yamlData, _ := json.Marshal(yourConfig) |
| 195 | + // Use YAML marshaling library to convert to YAML |
| 196 | + ``` |
| 197 | + |
| 198 | +2. **Direct Kubernetes client** - Use client-go: |
| 199 | + ```go |
| 200 | + import ( |
| 201 | + "k8s.io/client-go/kubernetes" |
| 202 | + "k8s.io/apimachinery/pkg/runtime" |
| 203 | + ) |
| 204 | + |
| 205 | + scheme := runtime.NewScheme() |
| 206 | + // Register your types with the scheme |
| 207 | + ``` |
| 208 | + |
| 209 | +## Additional Resources |
| 210 | + |
| 211 | +- [Go Package Documentation](https://pkg.go.dev/github.com/cozystack/cozystack/api/apps/v1alpha1) |
| 212 | +- [Cozystack GitHub Repository](https://github.com/cozystack/cozystack) |
| 213 | +- [Kubernetes API Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/) |
0 commit comments