# Integrating CoSky with Apache Dubbo for Microservice Governance: Complete Guide

> Successfully integrate CoSky with Apache Dubbo for microservice governance. Auto-register Dubbo providers with CoSky's Redis registry effortlessly using spring-cloud-starter-cosky-discovery.

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

---

**Integrating CoSky with Apache Dubbo requires adding the `spring-cloud-starter-cosky-discovery` dependency and enabling `auto-registration` in your Spring Boot configuration, allowing Dubbo providers to automatically register with CoSky's Redis-backed service registry without code changes.**

CoSky (Consistency + Sky) is a high-performance microservice governance platform built on Redis that provides service registration, discovery, and configuration management. This guide demonstrates how to integrate CoSky with Apache Dubbo in the `ahoo-wang/cosky` repository to achieve seamless microservice governance with sub-millisecond consistency propagation.

## Architectural Overview

CoSky integrates with Dubbo through Spring Cloud's discovery abstractions, allowing Dubbo 3.x to treat CoSky as a standard service registry. The architecture leverages Redis Pub/Sub and Lua scripts to ensure real-time consistency across distributed nodes.

### Service Registry Implementation

The core integration happens in [`CoSkyServiceRegistry.kt`](https://github.com/ahoo-wang/cosky/blob/main/CoSkyServiceRegistry.kt) located at [`cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyServiceRegistry.kt`](https://github.com/ahoo-wang/cosky/blob/main/cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyServiceRegistry.kt). This class implements Spring Cloud's `ServiceRegistry` interface and handles the registration, deregistration, and status management of Dubbo service instances.

When a Dubbo provider starts, the `register()` method writes service metadata—including service name, version, IP, port, weight, and TTL—directly to Redis using atomic Lua scripts. Consumers query this same data through `getInstances()` to resolve available endpoints.

### Auto-Registration Mechanism

The [`CoSkyAutoServiceRegistrationAutoConfiguration.kt`](https://github.com/ahoo-wang/cosky/blob/main/CoSkyAutoServiceRegistrationAutoConfiguration.kt) file provides Spring Boot auto-configuration that automatically creates a `CoSkyServiceRegistry` bean when Dubbo is detected on the classpath. This configuration triggers [`CoSkyAutoServiceRegistration.kt`](https://github.com/ahoo-wang/cosky/blob/main/CoSkyAutoServiceRegistration.kt) to register the provider during the `ApplicationStartedEvent` and gracefully deregister on shutdown, requiring zero manual registration code.

### Redis Consistency Layer

CoSky guarantees sub-millisecond propagation of service status changes using Redis Pub/Sub combined with Lua scripts stored in `cosky-discovery/src/main/resources/`. When a provider's weight changes or goes offline, the [`registry_register.lua`](https://github.com/ahoo-wang/cosky/blob/main/registry_register.lua) and [`registry_renew.lua`](https://github.com/ahoo-wang/cosky/blob/main/registry_renew.lua) scripts ensure atomic updates that instantly notify all consumer nodes without polling delays.

## Step-by-Step Integration Guide

### 1. Add Maven or Gradle Dependencies

Include the CoSky discovery starter alongside your Dubbo Spring Boot starter:

```xml
<dependency>
    <groupId>me.ahoo.cosky</groupId>
    <artifactId>spring-cloud-starter-cosky-discovery</artifactId>
    <version>${cosky.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-spring-boot-starter</artifactId>
    <version>3.2.7</version>
</dependency>

```

```kotlin
// Gradle Kotlin DSL
implementation("me.ahoo.cosky:spring-cloud-starter-cosky-discovery:${coskyVersion}")
implementation("org.apache.dubbo:dubbo-spring-boot-starter:3.2.7")

```

The `spring-cloud-starter-cosky-discovery` module brings in the `CoSkyServiceRegistry` implementation and all required Redis clients.

### 2. Configure CoSky Properties

Create or update [`bootstrap.yaml`](https://github.com/ahoo-wang/cosky/blob/main/bootstrap.yaml) to enable auto-registration and discovery:

```yaml
spring:
  cloud:
    cosky:
      namespace: ${cosky.namespace:cosky-${system}}
      service-registry:
        auto-registration:
          enabled: true
      discovery:
        enabled: true
      config:
        enabled: true
      registry:
        ttl: 30s
        weight: 100
        metadata:
          env: prod
          region: us-east-1

```

All properties map directly to the [`CoSkyRegistryProperties.kt`](https://github.com/ahoo-wang/cosky/blob/main/CoSkyRegistryProperties.kt) class, allowing customization of the service TTL, weight, and custom metadata that Dubbo consumers use for routing decisions.

### 3. Implement a Dubbo Provider

Create a standard Dubbo service interface and implementation:

```kotlin
package com.example.provider

import org.apache.dubbo.config.annotation.DubboService
import org.springframework.stereotype.Component

interface HelloService {
    fun sayHello(name: String): String
}

@DubboService(version = "1.0.0")
@Component
class HelloServiceImpl : HelloService {
    override fun sayHello(name: String) = "Hello, $name! (via CoSky-Dubbo)"
}

```

The `@DubboService` annotation marks this as a Dubbo provider. When the Spring Boot application starts, `CoSkyAutoServiceRegistration` automatically invokes `CoSkyServiceRegistry.register()` to publish this service to Redis.

### 4. Implement a Dubbo Consumer

Inject the Dubbo service reference into your consumer:

```kotlin
package com.example.consumer

import org.apache.dubbo.config.annotation.DubboReference
import org.springframework.stereotype.Component

@Component
class Caller(
    @DubboReference(version = "1.0.0")
    private val helloService: HelloService
) {
    fun greet(name: String): String = helloService.sayHello(name)
}

```

The consumer discovers provider instances through CoSky's `DiscoveryClient` implementation. Any weight changes or instance status updates in CoSky propagate instantly to the consumer's load balancer via Redis Pub/Sub.

### 5. Run the Application

Start the required infrastructure and services:

```bash

# Start Redis (required by CoSky)

docker run -d --name redis -p 6379:6379 redis:6-alpine

# Start the provider

./gradlew :provider:bootRun

# Start the consumer

./gradlew :consumer:bootRun

```

Check the console logs for CoSky registration events. The provider instance automatically registers on startup with the configured TTL and weight values.

### 6. Verify in CoSky Dashboard

Open the CoSky dashboard at `http://localhost:8080` and navigate to the **Service** tab. You will see the Dubbo provider instance listed with its full metadata including version, weight, and custom tags. Real-time status changes appear immediately without refresh.

## Key Source Files Reference

Understanding these specific source files helps debug and extend the integration:

- **[`cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyServiceRegistry.kt`](https://github.com/ahoo-wang/cosky/blob/main/cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyServiceRegistry.kt)** — Implements `ServiceRegistry<Registration>` with `register()`, `deregister()`, and `setStatus()` methods that write to Redis.
- **[`cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyRegistryProperties.kt`](https://github.com/ahoo-wang/cosky/blob/main/cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyRegistryProperties.kt)** — Defines configuration properties including `ttl`, `weight`, `namespace`, and `metadata` maps.
- **[`cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyAutoServiceRegistrationAutoConfiguration.kt`](https://github.com/ahoo-wang/cosky/blob/main/cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyAutoServiceRegistrationAutoConfiguration.kt)** — Spring Boot auto-configuration that creates the registry bean only when `spring.cloud.cosky.discovery.enabled` is true.
- **[`cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyAutoServiceRegistration.kt`](https://github.com/ahoo-wang/cosky/blob/main/cosky-spring-cloud-starter-discovery/src/main/kotlin/me/ahoo/cosky/discovery/spring/cloud/registry/CoSkyAutoServiceRegistration.kt)** — Lifecycle manager that hooks into Spring's `ApplicationStartedEvent` and shutdown hooks to manage registration state.
- **`cosky-discovery/src/main/resources/*.lua`** — Atomic Lua scripts for `registry_register`, `registry_renew`, and `registry_deregister` operations that ensure consistency during concurrent updates.

## Summary

- **CoSky** provides a Redis-backed service registry that integrates with **Apache Dubbo** through standard Spring Cloud DiscoveryClient abstractions.
- Adding `spring-cloud-starter-cosky-discovery` and setting `auto-registration.enabled: true` enables zero-code registration of Dubbo providers.
- The `CoSkyServiceRegistry` class handles all metadata publishing, while Lua scripts ensure atomic Redis operations for consistency.
- Consumers receive real-time updates via Redis Pub/Sub, enabling instant reaction to weight changes or instance outages.
- All configuration is centralized in [`bootstrap.yaml`](https://github.com/ahoo-wang/cosky/blob/main/bootstrap.yaml) through `CoSkyRegistryProperties`, supporting namespaces, TTL, and custom metadata.

## Frequently Asked Questions

### Does CoSky require modifications to existing Dubbo code?

No. CoSky integrates through Spring Cloud's `DiscoveryClient` and `ServiceRegistry` interfaces. Dubbo 3.x's `spring-cloud` module automatically detects CoSky as a valid registry when the dependency is present. Your existing `@DubboService` and `@DubboReference` annotations work without modification.

### How does CoSky handle health checking for Dubbo services?

CoSky uses a TTL (time-to-live) mechanism defined in `CoSkyRegistryProperties`. Providers must periodically renew their registration (automatically handled by `CoSkyAutoServiceRegistration`), and if a provider fails to renew within the configured TTL (default 30 seconds), CoSky marks the instance as offline and broadcasts the change to consumers via Redis Pub/Sub.

### What Redis version is required for CoSky Dubbo integration?

CoSky requires Redis 6.0 or higher to support the Lua scripting and Pub/Sub features used by the consistency layer. The scripts in `cosky-discovery/src/main/resources/` use atomic operations that require Redis's single-threaded execution model to guarantee consistency during concurrent registration updates.

### Can I use CoSky with Dubbo 2.x?

While CoSky's Spring Cloud integration primarily targets Dubbo 3.x, you can use CoSky with Dubbo 2.x by manually implementing the `MetadataReport` interface to bridge CoSky's `CoSkyServiceRegistry`. However, Dubbo 3.2.7 or higher is recommended for seamless automatic integration through the `dubbo-spring-boot-starter`.