Service

Understanding Odin services and how to define them

A Service in Odin represents a deployable application unit composed of one or more components. Services are the primary abstraction for managing your applications in Odin.

What is a Service?

A service is a functional unit with defined boundaries that:

• Consists of one or more components (web servers, databases, caches, etc.)
• Can be treated as a blackbox from the outside
• Is versioned and can be deployed independently
• Has lifecycle states and can be operated as a unit

Service Definition

Services are defined using JSON files with the following structure:

{ "name": "user-api",
  "version": "1.0.0",
  "team": "backend-team",
  "components": [
    {"name": "api-server",
      "type": "webservice",
      "version": "2.1.0",
      "depends_on": ["database", "cache"],
      "config": {  "port": 8080,
        "replicas": 3
      
    ,
    {"name": "database",
      "type": "postgres",
      "version": "14.5",
      "config": {  "storage": "100Gi"
      
    ,
    {"name": "cache",
      "type": "redis",
      "version": "7.0",
      "config": {  "memory": "2Gi"
      
    
  ]

Service Properties

Service Lifecycle

Deploying a Service

Deploy a service to an environment:

odin deploy service --env <env-name> \
  --file service.json \
  --provisioning provisioning.json

The deployment process:

1. Validates the service definition
2. Validates provisioning configuration
3. Creates deployment tasks for each component
4. Deploys components according to dependency order
5. Monitors deployment status and reports progress

Service States

Services transition through several states during their lifecycle:

Checking Service Status

Check the status of a deployed service:

odin status env <env-name> --service <service-name>

Get detailed component-level information:

odin describe env <env-name> --service <service-name>

Undeploying a Service

Remove a service from an environment:

odin undeploy service <service-name> --env <env-name>

Service Operations

Operating a Service

Execute lifecycle operations on a service:

odin operate service --name <service-name>   --env <env-name>   --operation <operation-type>   --options '{"key": "value"}'

Redeploying a Service

Update a service with new configuration:

odin operate service --name user-api \
  --env staging \
  --operation redeploy \
  --file updated-service.json

When redeploying, Odin shows a diff of pending changes and asks for confirmation.

Service Versioning

Odin supports two versioning strategies:

SNAPSHOT Versions

Mutable versions for development and QA:

{ "name": "user-api",
  "version": "1.2.0-SNAPSHOT",
  ...

• Can be redeployed with changes
• Ideal for fast iteration
• Not suitable for production

CONCRETE Versions

Immutable versions for production:

{ "name": "user-api",
  "version": "1.2.0",
  ...

• Cannot be modified once released
• Guarantees reproducibility
• Suitable for production deployments

Service Best Practices

Service Definition

1. Use Semantic Versioning: Follow major.minor.patch format
2. Document Dependencies: Clearly specify depends_on relationships
3. Modular Components: Break services into logical components
4. Team Ownership: Assign clear team ownership

Development Workflow

1. Develop with SNAPSHOT: Deploy 1.0.0-SNAPSHOT to dev environment
2. Iterate with QA: Test and refine in staging environment
3. Release CONCRETE: Create 1.0.0 release for production
4. Deploy to Production: Deploy immutable version to prod

Examples

Simple Web Service

{ "name": "hello-world",
  "version": "1.0.0-SNAPSHOT",
  "team": "platform",
  "components": [
    {"name": "web",
      "type": "webservice",
      "version": "1.0.0",
      "config": {  "port": 8080
      
    
  ]

Related Concepts

• Component: Building blocks of services
• Provisioning: Define how services are deployed
• Environment: Where services are deployed