Skip to content

Getting Started

Prerequisites

1. Install the Operator

helm install naftiko-skipper \
  oci://ghcr.io/naftiko/skipper/helm/naftiko-skipper \
  --namespace naftiko-system --create-namespace

kubectl rollout status deployment/naftiko-skipper \
  -n naftiko-system --timeout=60s

Verify the operator and default CapabilityClasses are ready:

kubectl get pods -n naftiko-system
kubectl get capabilityclass
# NAME       AGE
# dev        ...
# premium    ...
# standard   ...

2. Write Your Capability Spec

Save this as hello-world.yaml — just the ikanos spec, no Kubernetes wrapper:

ikanos: "1.0.0-alpha4"
info:
  display: Hello World
  description: "Simple hello world REST capability"
  tags:
    - rest
  labels:
    naftiko.io/domain: platform
    naftiko.io/tier: standard
capability:
  exposes:
    - type: rest
      address: "0.0.0.0"
      port: 3001
      namespace: tutorial
      resources:
        hello:
          path: /hello
          display: My first resource
          description: Simple Hello, World! API endpoint
          operations:
            get-hello:
              method: GET
              outputParameters:
                - name: message
                  type: string
                  value: "Hello, World!"
    - type: control
      address: "0.0.0.0"
      port: 9090
      observability:
        enabled: true
        metrics:
          local:
            enabled: true
        traces:
          sampling: 1.0
          propagation: w3c

The type: control expose activates the observability endpoint at /metrics, /health/live, and /health/ready. It is optional but recommended.

3. Upload the Spec to Kubernetes

kubectl create configmap hello-world-spec \
  --from-file=capability.yaml=hello-world.yaml \
  -n default

Verify the content was loaded correctly:

kubectl get configmap hello-world-spec -n default \
  -o jsonpath='{.data.capability\.yaml}' | head -3

Expected output:

ikanos: "1.0.0-alpha4"
info:
  display: Hello World

4. Apply the Capability CR

kubectl apply -f - <<EOF
apiVersion: naftiko.io/v1alpha3
kind: Capability
metadata:
  name: hello-world
  namespace: default
  labels:
    naftiko.io/tier: standard
spec:
  specRef:
    configMap: hello-world-spec
EOF

5. Wait for the Pod to Be Ready

kubectl wait pod -l naftiko.io/capability=hello-world \
  --for=condition=Ready --timeout=60s -n default

Check what the operator created:

# Service with both ports (rest + control)
kubectl get svc hello-world -n default \
  -o jsonpath='{.spec.ports[*].name}'
# → rest control

# ServiceMonitor for Prometheus
kubectl get servicemonitor hello-world -n default

# Capability status
kubectl get capability hello-world -n default
# NAME          PHASE     ENDPOINT
# hello-world   Running   http://hello-world.default.svc.cluster.local:3001

Note: If ServiceMonitor is not found, Prometheus Operator may not be installed yet. Install it first, then restart the operator: 

kubectl rollout restart deployment/naftiko-skipper -n naftiko-system

6. Test the Endpoints

kubectl port-forward svc/hello-world 3001:3001 9090:9090 -n default &
sleep 2

# Business endpoint
curl http://localhost:3001/hello
# → {"message": "Hello, World!"}

# Health
curl http://localhost:9090/health/live
# → {"status":"UP"}

# Metrics
curl -s http://localhost:9090/metrics | grep ikanos_request_total

7. Generate Traffic and Observe Metrics

for i in $(seq 1 20); do curl -s http://localhost:3001/hello > /dev/null; done

curl -s http://localhost:9090/metrics \
  | grep -E "ikanos_request_total|ikanos_capability_active"

Expected output:

ikanos_capability_active{ikanos_capability="Hello World"} 1
ikanos_request_total{...,status="200"} 20

8. Cleanup

pkill -f "port-forward"
kubectl delete capability hello-world -n default
kubectl delete configmap hello-world-spec -n default

Next Steps