micro--go-micro
Asim Aslam
96280678ee
* feat: expose framework primitives via API gateway and MCP
Add registry, store, and broker as both HTTP routes and MCP tools
so AI agents and HTTP clients can inspect and operate the framework.
API gateway (/micro/* namespace):
GET /micro/registry List registered services
GET /micro/registry/{name} Describe a service
GET /micro/store List store keys
GET /micro/store/{key} Read a record
POST /micro/store/{key} Write a record
POST /micro/broker/{topic} Publish a message
MCP gateway (micro_* tool prefix):
micro_registry_list List services
micro_registry_get Describe a service
micro_store_list List keys
micro_store_read Read a record
micro_store_write Write a record
micro_broker_publish Publish a message
Framework tools use a Handler field on the MCP Tool struct for
direct dispatch (no RPC). Service tools continue to use RPC.
Rate limiters and circuit breakers are applied to framework
tools the same as service tools.
* fix: make framework internals opt-in on API and MCP gateways
Framework primitives (registry, broker, store) are now only
exposed when explicitly enabled:
API gateway: micro api --internal
MCP gateway: Options{Internal: true}
Off by default — user services are always exposed, framework
internals require the flag. Banner output only shows framework
routes when enabled.
* fix: always expose framework internals, gate by auth in production
Revert the --internal flag approach. Framework primitives (registry,
broker, store) are now always exposed:
- micro api: /micro/* routes always available (dev tool)
- MCP gateway: micro_* tools always registered. When Auth is
configured (production), they require micro:admin scope.
Without Auth (dev), they're open — same as all other tools.
This follows the existing pattern: micro run/api = dev (open),
micro server = production (auth + scopes). Framework internals
follow the same security model as user services.
Remove the Internal option from MCP Options. Remove --internal
flag from micro api.
Note: scope persistence depends on the store backend. The default
in-memory store does not survive restarts. Use MICRO_STORE=file
for persistent scopes in production.
* fix: correct DefaultStore comment — it's file-backed, not memory
* fix(server): don't recreate deleted admin user on restart
When the default admin account is deleted via the dashboard, set
a marker key (auth/.admin-deleted) in the store. On startup, skip
admin creation if the marker exists. This prevents the default
admin/micro credentials from reappearing after restart when the
user has intentionally removed them.
* fix: improve agent playground first-run UX and fix doc 404s
Agent playground:
- Add setup hint in empty state explaining how to get started
(click Settings, enter API key, type a prompt)
- Hide hint automatically when API key is already configured
- Add all 7 providers to dropdown (was only OpenAI + Anthropic)
- Include CLI fallback suggestion (micro chat)
Docs:
- Fix .md links to .html across all doc pages — Jekyll serves
.html files, not .md. Fixes 404s including the micro run guide.
---------
Co-authored-by: Claude <noreply@anthropic.com>
218 行
9.0 KiB
Markdown
218 行
9.0 KiB
Markdown
---
|
|
layout: default
|
|
title: Hosting
|
|
---
|
|
|
|
# Hosting Go Micro Services
|
|
|
|
This document outlines what hosting looks like for go-micro services, the options available today, and what an ideal hosting platform would provide.
|
|
|
|
## Overview
|
|
|
|
Go Micro services are compiled Go binaries that communicate via RPC and event-driven messaging. Hosting them requires infrastructure that supports service discovery, inter-service communication, persistent storage, and configuration management. Because go-micro uses a pluggable architecture, the hosting environment can range from a single VPS to a fully orchestrated cluster.
|
|
|
|
## Current Hosting Options
|
|
|
|
### Single VPS or Bare Metal
|
|
|
|
The simplest approach. Deploy compiled binaries to a Linux server and manage them with systemd. This is the model described in the [Deployment Guide](deployment.html).
|
|
|
|
**Good for:** Small teams, early-stage projects, predictable workloads.
|
|
|
|
```
|
|
Server
|
|
├── micro@users.service
|
|
├── micro@posts.service
|
|
├── micro@web.service
|
|
└── mdns for discovery
|
|
```
|
|
|
|
- Use `micro deploy` to push binaries over SSH
|
|
- systemd handles process supervision and restarts
|
|
- mDNS provides zero-configuration service discovery on the local host
|
|
- Environment files supply per-service configuration
|
|
|
|
### Multiple Servers
|
|
|
|
Run services across several machines. This requires replacing mDNS with a network-aware registry like Consul or Etcd so services can discover each other across hosts.
|
|
|
|
```bash
|
|
# Point all services at a shared registry
|
|
MICRO_REGISTRY=consul MICRO_REGISTRY_ADDRESS=consul.internal:8500
|
|
```
|
|
|
|
- Deploy with `micro deploy` to each target server
|
|
- Use a central registry (Consul, Etcd, or NATS) for cross-host discovery
|
|
- Place a load balancer or API gateway in front of public-facing services
|
|
|
|
### Containers and Kubernetes
|
|
|
|
Package each service as a Docker image and deploy to a Kubernetes cluster or a simpler container runtime like Docker Compose.
|
|
|
|
**Dockerfile example:**
|
|
|
|
```dockerfile
|
|
FROM golang:1.21-alpine AS build
|
|
WORKDIR /app
|
|
COPY . .
|
|
RUN go build -o service ./cmd/service
|
|
|
|
FROM alpine:3.19
|
|
COPY --from=build /app/service /service
|
|
ENTRYPOINT ["/service"]
|
|
```
|
|
|
|
**Kubernetes considerations:**
|
|
|
|
- Use the Kubernetes registry plugin or run Consul/Etcd as a StatefulSet
|
|
- ConfigMaps and Secrets replace environment files
|
|
- Kubernetes Services and Ingress handle external traffic
|
|
- Horizontal Pod Autoscaler manages scaling
|
|
- Liveness and readiness probes map to go-micro health checks
|
|
|
|
### Platform as a Service (PaaS)
|
|
|
|
Deploy to managed platforms like Railway, Render, or Fly.io. Each service runs as a separate application.
|
|
|
|
- Configuration via platform-provided environment variables
|
|
- Managed TLS and load balancing out of the box
|
|
- Use NATS or a hosted registry for service discovery between apps
|
|
- Limited control over networking and co-location
|
|
|
|
## What a Hosting Platform Needs
|
|
|
|
A purpose-built platform for go-micro services would integrate with the framework's core abstractions rather than treating services as generic containers.
|
|
|
|
### Service Discovery
|
|
|
|
The platform must run or integrate with a supported registry so services find each other automatically.
|
|
|
|
| Environment | Recommended Registry |
|
|
|---|---|
|
|
| Single host | mDNS (default, zero config) |
|
|
| Multi-host / cloud | Consul, Etcd, or NATS |
|
|
| Kubernetes | Kubernetes registry plugin |
|
|
|
|
### RPC and Messaging
|
|
|
|
Services communicate over RPC (request/response) and asynchronous messaging (pub/sub). The platform must allow direct service-to-service communication on the configured transport.
|
|
|
|
- **Transport:** HTTP (default), gRPC, or NATS
|
|
- **Broker:** HTTP event broker (default), NATS, or RabbitMQ
|
|
- Internal traffic should stay on a private network
|
|
- External traffic flows through a gateway or load balancer
|
|
|
|
### Configuration Management
|
|
|
|
Each service loads configuration from environment variables, files, or remote sources. The platform should provide:
|
|
|
|
- Per-service environment variables or config files
|
|
- Secret management with restricted access
|
|
- Hot-reload support for dynamic configuration changes
|
|
|
|
### Data Storage
|
|
|
|
go-micro's store interface supports multiple backends. The platform should provide or connect to durable storage.
|
|
|
|
- **Development:** In-memory store (default)
|
|
- **Production:** Postgres, MySQL, Redis, or other supported backends
|
|
- Persistent volumes or managed database services for stateful data
|
|
|
|
### Health Checks and Observability
|
|
|
|
The platform should monitor service health and provide visibility into behavior.
|
|
|
|
- **Health endpoints** for liveness and readiness
|
|
- **Structured logs** collected and searchable
|
|
- **Metrics** (request rates, latencies, error rates) scraped or pushed
|
|
- **Distributed tracing** across service boundaries
|
|
|
|
See [Observability](observability.html) for details on logs, metrics, and traces.
|
|
|
|
### Security
|
|
|
|
- TLS for all inter-service communication
|
|
- Service-level authentication and authorization via go-micro's auth interface
|
|
- Network isolation between services and the public internet
|
|
- Secret rotation and audit logging
|
|
|
|
### Scaling
|
|
|
|
- Horizontal scaling: run multiple instances of a service behind the client-side load balancer
|
|
- The registry tracks all instances; the selector distributes requests
|
|
- Auto-scaling based on resource usage or request volume
|
|
|
|
## Ideal Platform Architecture
|
|
|
|
A hosting platform tailored for go-micro would look like this:
|
|
|
|
```
|
|
┌──────────────┐
|
|
Internet ──────▶│ Gateway │
|
|
└──────┬───────┘
|
|
│
|
|
┌────────────┼────────────┐
|
|
│ │ │
|
|
┌─────▼────┐ ┌────▼─────┐ ┌───▼──────┐
|
|
│ Service A │ │ Service B│ │ Service C │
|
|
│ (n inst.) │ │ (n inst.)│ │ (n inst.) │
|
|
└─────┬────┘ └────┬─────┘ └───┬──────┘
|
|
│ │ │
|
|
┌─────────▼────────────▼────────────▼─────────┐
|
|
│ Private Network │
|
|
│ ┌──────────┐ ┌───────┐ ┌──────────────┐ │
|
|
│ │ Registry │ │ Broker│ │ Store │ │
|
|
│ │(Consul/ │ │(NATS/ │ │(Postgres/ │ │
|
|
│ │ Etcd) │ │ Redis)│ │ MySQL/Redis) │ │
|
|
│ └──────────┘ └───────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Platform Capabilities
|
|
|
|
1. **Deploy** — Push binaries or container images; the platform registers them with the registry
|
|
2. **Discover** — Built-in registry so services find each other without manual configuration
|
|
3. **Route** — Gateway for external traffic; direct RPC for internal traffic
|
|
4. **Scale** — Add or remove instances; the registry and selector handle rebalancing
|
|
5. **Configure** — Environment variables, secrets, and dynamic config per service
|
|
6. **Observe** — Centralized logs, metrics dashboards, and trace visualization
|
|
7. **Secure** — Automatic TLS, service identity, and network policies
|
|
|
|
### Deployment Workflow
|
|
|
|
```
|
|
Developer Platform
|
|
──────── ────────
|
|
micro build ─────▶ Receive binary/image
|
|
micro deploy prod ─────▶ Place on compute
|
|
Register with discovery
|
|
Start health checks
|
|
Route traffic
|
|
```
|
|
|
|
## Choosing a Hosting Strategy
|
|
|
|
| Factor | Single VPS | Multi-Server | Kubernetes | PaaS |
|
|
|---|---|---|---|---|
|
|
| Complexity | Low | Medium | High | Low |
|
|
| Cost | Low | Medium | High | Variable |
|
|
| Scaling | Manual | Manual | Automatic | Automatic |
|
|
| Service discovery | mDNS | Consul/Etcd/NATS | Plugin or Consul | External |
|
|
| Ops overhead | Minimal | Moderate | Significant | Minimal |
|
|
| Best for | Prototypes, small apps | Growing teams | Large-scale production | Quick launches |
|
|
|
|
## Getting Started
|
|
|
|
1. **Start simple** — Deploy to a single server with `micro deploy` and mDNS
|
|
2. **Add a registry** — When you need multiple servers, switch to Consul or Etcd
|
|
3. **Containerize** — When you need reproducible environments, add Docker
|
|
4. **Orchestrate** — When you need auto-scaling and self-healing, move to Kubernetes or a PaaS
|
|
|
|
## Related
|
|
|
|
- [Deployment](deployment.html) — Deploy services to a Linux server with systemd
|
|
- [Registry](registry.html) — Service discovery backends
|
|
- [Architecture](architecture.html) — Go Micro design and components
|
|
- [Observability](observability.html) — Logs, metrics, and tracing
|
|
- [Performance](performance.html) — Performance characteristics and tuning
|