# How to Deploy CoSky as a Kubernetes Microservice: Complete Guide

> Deploy CoSky as a Kubernetes microservice using the official manifests from ahoo-wang/cosky. Configure Redis host and expose port 8080 to run your microservice efficiently.

- Repository: [Ahoo Wang/cosky](https://github.com/ahoo-wang/cosky)
- Tags: getting-started
- Published: 2026-02-23

---

**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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky.yml), locate the `env` section and update:

```yaml
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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky.yml) file defines the Deployment with resource limits, startup probes, and volume mounts for timezone synchronization. Deploy it using:

```bash
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:

```bash
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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky-service.yaml) uses a selector `app: cosky` to route traffic to the deployment pods:

```yaml
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:

```bash
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:

```bash
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:

```yaml
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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky.yml):

```yaml
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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky.yml)) configures the container image, resource limits, health probes, and Redis connection parameters.
- The **Service** manifest ([`k8s/deployment/cosky-service.yaml`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/k8s/deployment/cosky-service.yaml). You can verify this by checking the `containerPort: 8080` specification in [`k8s/deployment/cosky.yml`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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`](https://github.com/ahoo-wang/cosky/blob/main/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.