How to Deploy CoSky as a Kubernetes Microservice: Complete Guide

Deploy CoSky as a Kubernetes microservice by applying the official Deployment and Service manifests from the ahoo-wang/cosky repository, configuring the SPRING_DATA_REDIS_HOST environment variable, and exposing port 8080 through a Kubernetes Service.

CoSky is a lightweight, high-performance microservice governance platform built on Spring Boot and Redis. When you deploy CoSky as a Kubernetes microservice, you run the containerized REST API server with integrated health probes, resource limits, and service discovery capabilities.

Architecture Overview

CoSky follows a standard cloud-native architecture where the application container connects to an external Redis backend for state management.

Container Structure

The deployment uses the official container image registry.cn-shanghai.aliyuncs.com/ahoo/cosky:4.0.0 as defined in cosky-rest-api/Dockerfile. The Spring Boot application starts on port 8080 and exposes actuator endpoints at /actuator/health for Kubernetes probe integration.

Networking and Service Exposure

According to the source code in k8s/deployment/cosky-service.yaml, the Service resource creates a stable endpoint that maps external port 80 to the container's port 8080. This abstraction allows microservice clients to discover CoSky via DNS (http://cosky.<namespace>.svc.cluster.local) without hardcoding pod IPs.

Prerequisites

Before deploying CoSky to Kubernetes, ensure you have:

• A running Kubernetes cluster (version 1.20+)
• kubectl configured to communicate with your cluster
• A Redis instance accessible from the cluster (deployed within the same namespace or externally)
• Optional: A namespace dedicated to CoSky (kubectl create namespace cosky)

Step-by-Step Deployment

Configure Redis Connectivity

CoSky stores service registry and configuration data in Redis. You must configure the connection via environment variables in the Deployment manifest. In k8s/deployment/cosky.yml, locate the env section and update:

env:
  - name: SPRING_DATA_REDIS_HOST
    value: "redis:6379"  # Change to your Redis host:port

  - name: SPRING_DATA_REDIS_PASSWORD
    value: ""            # Add password if Redis requires authentication

  - name: TZ
    value: "Asia/Shanghai"
  - name: JAVA_OPTS
    value: "-Djava.net.preferIPv4Stack=true"

Apply the Deployment Manifest

The k8s/deployment/cosky.yml file defines the Deployment with resource limits, startup probes, and volume mounts for timezone synchronization. Deploy it using:

kubectl apply -f https://raw.githubusercontent.com/ahoo-wang/cosky/main/k8s/deployment/cosky.yml -n cosky

This creates a pod running the CoSky REST API with the following specifications from the source:

• Resources: Limits of 1 CPU and 1280Mi memory, requests of 250m CPU and 1024Mi memory
• Probes:
  • startupProbe checks /actuator/health to delay other probes until startup completes
  • readinessProbe validates /actuator/health/readiness for traffic routing
  • livenessProbe monitors /actuator/health/liveness for container restart decisions

Expose the Service

Apply the Service manifest to create a stable network endpoint:

kubectl apply -f https://raw.githubusercontent.com/ahoo-wang/cosky/main/k8s/deployment/cosky-service.yaml -n cosky

The Service configuration in k8s/deployment/cosky-service.yaml uses a selector app: cosky to route traffic to the deployment pods:

apiVersion: v1
kind: Service
metadata:
  name: cosky
  labels:
    app: cosky
spec:
  selector:
    app: cosky
  ports:
    - name: rest
      port: 80
      targetPort: 8080
      protocol: TCP

Verify the Deployment

Check the rollout status and pod health:

kubectl rollout status deployment/cosky -n cosky
kubectl get pods -n cosky -l app=cosky
kubectl get svc cosky -n cosky

For local testing without a LoadBalancer, use port forwarding:

kubectl port-forward svc/cosky 8080:80 -n cosky

# Access at http://localhost:8080

Configuration Options

Environment Variables

The CoSky container accepts several environment variables defined in the Deployment spec:

• SPRING_DATA_REDIS_HOST: Redis server address (required)
• SPRING_DATA_REDIS_PASSWORD: Redis authentication password (optional)
• TZ: Container timezone (default: Asia/Shanghai)
• JAVA_OPTS: JVM arguments for tuning heap size or network preferences

Resource Limits and Probes

The source manifest defines production-grade resource constraints:

resources:
  limits:
    cpu: "1"
    memory: 1280Mi
  requests:
    cpu: 250m
    memory: 1024Mi

The probe configuration ensures zero-downtime deployments by verifying application readiness before marking pods as available.

Production Considerations

High Availability with StatefulSet

For clustered deployments requiring multiple CoSky instances with stable network identities, use k8s/deployment/cosky-cluster.yml. This StatefulSet configuration provides ordered deployment and persistent identity for each replica, suitable for running CoSky in cluster mode with Raft consensus.

Security Context

When deploying to production, consider adding security contexts to the container spec in k8s/deployment/cosky.yml:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true

Additionally, store sensitive Redis credentials in Kubernetes Secrets rather than plain environment variables.

Summary

• CoSky deploys as a standard Spring Boot container on Kubernetes, requiring only Redis as a backend dependency.
• The Deployment manifest (k8s/deployment/cosky.yml) configures the container image, resource limits, health probes, and Redis connection parameters.
• The Service manifest (k8s/deployment/cosky-service.yaml) exposes port 8080 internally and maps it to port 80 for client access.
• Environment variables SPRING_DATA_REDIS_HOST and SPRING_DATA_REDIS_PASSWORD control the critical Redis connectivity.
• For high availability, substitute the Deployment with the StatefulSet configuration in k8s/deployment/cosky-cluster.yml.

Frequently Asked Questions

What is the default port for CoSky in Kubernetes?

CoSky listens on port 8080 inside the container. The Kubernetes Service maps this to port 80 for external access, as defined in k8s/deployment/cosky-service.yaml. You can verify this by checking the containerPort: 8080 specification in k8s/deployment/cosky.yml.

Does CoSky require persistent storage when deployed to Kubernetes?

No, the standard Deployment does not require persistent volumes. CoSky stores all state in Redis, making the application containers stateless. However, if you deploy using the cosky-cluster.yml StatefulSet for high availability, you may need persistent storage for the Raft log depending on your specific configuration.

How do I configure CoSky to use an external Redis instance?

Set the SPRING_DATA_REDIS_HOST environment variable in the Deployment manifest to point to your external Redis endpoint (e.g., redis.example.com:6379). If authentication is required, provide the password via SPRING_DATA_REDIS_PASSWORD. These variables are processed by the Spring Data Redis auto-configuration in the CoSky application.

Can I run multiple replicas of CoSky for high availability?

Yes, you can scale the Deployment using kubectl scale deployment cosky --replicas=3, but for true high availability with consistent clustering, use the StatefulSet configuration in k8s/deployment/cosky-cluster.yml. The StatefulSet provides stable network identities and ordered startup required for the Raft consensus algorithm used in CoSky cluster mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}