Merge pull request #5 from mNi-Cloud/add_ionscale

Add ionscale

Author: MuNeNiCK

.github/workflows/lint.yml

@@ -20,4 +20,4 @@ jobs:
       - name: Run linter
         uses: golangci/golangci-lint-action@v6
         with:
-          version: v1.63.4
+          version: v1.64.2

Dockerfile

@@ -1,5 +1,5 @@
 # Build the manager binary
-FROM docker.io/golang:1.23 AS builder
+FROM docker.io/golang:1.24 AS builder
 ARG TARGETOS
 ARG TARGETARCH
 

PROJECT

@@ -17,4 +17,31 @@ resources:
   kind: Connector
   path: github.com/mNi-Cloud/kodiak/api/v1alpha1
   version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: mnicloud.jp
+  group: kodiak
+  kind: ControlServer
+  path: github.com/mNi-Cloud/kodiak/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: mnicloud.jp
+  group: kodiak
+  kind: Tailnet
+  path: github.com/mNi-Cloud/kodiak/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: mnicloud.jp
+  group: kodiak
+  kind: AuthKey
+  path: github.com/mNi-Cloud/kodiak/api/v1alpha1
+  version: v1alpha1
 version: "3"

README.md

@@ -1,8 +1,35 @@
 # kodiak
-// TODO(user): Add simple overview of use/purpose
+
+Kodiak is a Kubernetes Operator that provisions and manages a full self-hosted
+Tailscale environment powered by [ionscale](https://github.com/jsiebens/ionscale).
+It automates creation of the ionscale control plane, tailnets, authentication
+keys, and the connector workloads that join Kubernetes networks to Tailscale.
 
 ## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
+
+Kodiak exposes four custom resources (`ControlServer`, `Tailnet`, `AuthKey`, and
+`Connector`) that map directly to the lifecycle of an ionscale deployment:
+
+- **ControlServer** provisions the ionscale API/control plane, including TLS
+  configuration, embedded DERP options, persistent storage, and optional OIDC
+  authentication. The controller renders ionscale configuration, wires any
+  referenced secrets (e.g. the system admin key), and maintains a Deployment,
+  Service, and PersistentVolumeClaim to run the server. Status reflects the
+  service endpoint and readiness.
+- **Tailnet** configures a tailnet on the control server. The controller calls
+  ionscale's API to create or update tailnet state (policies, DNS, feature
+  flags) and reports readiness, the assigned tailnet ID, and machine counts.
+- **AuthKey** manages short-lived authentication keys for joining nodes to a
+  tailnet. Kodiak requests keys from ionscale, stores the resulting value in a
+  Kubernetes secret, keeps status in sync with ionscale, and rotates keys when
+  specs change.
+- **Connector** (existing implementation) runs a Tailscale client pod that
+  connects Kubernetes networks to the tailnet, handling auth key injection,
+  connector pod lifecycle, and status reporting based on `tailscale status`.
+
+The controllers reconcile towards declarative state, use Kubernetes
+finalizers to clean up remote resources (e.g. deleting tailnets or auth keys),
+and surface detailed conditions in resource status.
 
 ## Getting Started
 
@@ -111,7 +138,27 @@ previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml
 is manually re-applied afterwards.
 
 ## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
+### Required Secrets
+
+Control server access requires a system admin key. By default Kodiak expects a
+secret named `<controlserver-name>-admin` in the same namespace with a
+`systemAdminKey` entry. You can override the secret name using the annotation
+`kodiak.mnicloud.jp/system-admin-key-secret` on the `ControlServer` resource.
+
+Auth keys are stored in Kubernetes secrets. If `spec.secretName` is omitted the
+controller creates a secret named `authkey-<resource-name>` containing a
+`TS_AUTH_KEY` entry.
+
+### Development Notes
+
+- Controller unit tests use `envtest`. Install the Kubernetes control-plane
+  binaries (etcd, kube-apiserver, kubectl) via `make envtest` before running
+  `go test ./...`.
+- E2E tests rely on Docker and Kind. Expect failures if these dependencies are
+  unavailable in the current environment.
+
+Please open issues or pull requests for bugs, enhancements, or documentation
+updates.
 
 **NOTE:** Run `make help` for more information on all potential `make` targets
 
@@ -132,4 +179,3 @@ distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-

api/v1alpha1/authkey_types.go

@@ -0,0 +1,132 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
+// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+
+// AuthKeySpec defines the desired state of AuthKey
+type AuthKeySpec struct {
+	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// +kubebuilder:validation:Required
+	// TailnetRef references the Tailnet this auth key belongs to
+	TailnetRef corev1.LocalObjectReference `json:"tailnetRef"`
+
+	// +optional
+	// +kubebuilder:default=false
+	// Ephemeral determines if machines authenticated with this key are ephemeral
+	Ephemeral bool `json:"ephemeral,omitempty"`
+
+	// +optional
+	// Expiry duration for the auth key (e.g., "24h", "7d")
+	Expiry string `json:"expiry,omitempty"`
+
+	// +optional
+	// Tags to apply to machines authenticated with this key
+	Tags []string `json:"tags,omitempty"`
+
+	// +optional
+	// +kubebuilder:default=false
+	// PreAuthorized determines if machines are automatically authorized
+	PreAuthorized bool `json:"preAuthorized,omitempty"`
+
+	// +optional
+	// SecretName to store the generated auth key (defaults to authkey-<name>)
+	SecretName string `json:"secretName,omitempty"`
+}
+
+// AuthKeyStatus defines the observed state of AuthKey.
+type AuthKeyStatus struct {
+	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// +optional
+	// KeyID is the ID assigned by the control server
+	KeyID uint64 `json:"keyId,omitempty"`
+
+	// +optional
+	// SecretRef references the secret containing the auth key
+	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"`
+
+	// +optional
+	// CreatedAt is when the key was created
+	CreatedAt *metav1.Time `json:"createdAt,omitempty"`
+
+	// +optional
+	// ExpiresAt is when the key expires
+	ExpiresAt *metav1.Time `json:"expiresAt,omitempty"`
+
+	// +optional
+	// Ready indicates if the auth key is ready for use
+	Ready bool `json:"ready,omitempty"`
+
+	// +optional
+	// Phase represents the current phase of the auth key
+	Phase string `json:"phase,omitempty"`
+
+	// conditions represent the current state of the AuthKey resource.
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:printcolumn:name="READY",type="boolean",JSONPath=".status.ready",description="Auth key ready status"
+// +kubebuilder:printcolumn:name="TAILNET",type="string",JSONPath=".spec.tailnetRef.name",description="Tailnet reference"
+// +kubebuilder:printcolumn:name="EPHEMERAL",type="boolean",JSONPath=".spec.ephemeral",description="Ephemeral key"
+// +kubebuilder:printcolumn:name="PREAUTH",type="boolean",JSONPath=".spec.preAuthorized",description="Pre-authorized"
+// +kubebuilder:printcolumn:name="EXPIRES",type="date",JSONPath=".status.expiresAt",description="Expiration time"
+// +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp"
+
+// AuthKey is the Schema for the authkeys API
+type AuthKey struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
+
+	// spec defines the desired state of AuthKey
+	// +required
+	Spec AuthKeySpec `json:"spec"`
+
+	// status defines the observed state of AuthKey
+	// +optional
+	Status AuthKeyStatus `json:"status,omitempty,omitzero"`
+}
+
+// +kubebuilder:object:root=true
+
+// AuthKeyList contains a list of AuthKey
+type AuthKeyList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []AuthKey `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&AuthKey{}, &AuthKeyList{})
+}

api/v1alpha1/connector_types.go

@@ -17,6 +17,7 @@ limitations under the License.
 package v1alpha1
 
 import (
+	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
@@ -74,9 +75,17 @@ type ConnectorSpecSpec struct {
 }
 
 type TailscaleConfig struct {
-	// +kubebuilder:validation:Required
-	// Auth key used for Tailscale authentication
-	AuthKey string `json:"authKey"`
+	// +optional
+	// Auth key used for Tailscale authentication (mutually exclusive with AuthKeyRef)
+	AuthKey string `json:"authKey,omitempty"`
+
+	// +optional
+	// AuthKeySecretRef references an existing secret containing TS_AUTH_KEY (mutually exclusive with AuthKey and AuthKeyRef)
+	AuthKeySecretRef *corev1.SecretKeySelector `json:"authKeySecretRef,omitempty"`
+
+	// +optional
+	// AuthKeyRef references an AuthKey resource to use for authentication
+	AuthKeyRef *corev1.LocalObjectReference `json:"authKeyRef,omitempty"`
 
 	// +kubebuilder:default="stable"
 	// +optional
@@ -102,8 +111,12 @@ type TailscaleConfig struct {
 	AcceptDNS bool `json:"acceptDns,omitempty"`
 
 	// +optional
-	// URL for custom Tailscale control server (e.g., Headscale)
+	// URL for custom Tailscale control server (mutually exclusive with ControlServerRef)
 	ControlServerUrl string `json:"controlServerUrl,omitempty"`
+
+	// +optional
+	// ControlServerRef references a ControlServer resource to use
+	ControlServerRef *corev1.LocalObjectReference `json:"controlServerRef,omitempty"`
 }
 
 // ConnectorStatus defines the observed state of Connector.