Initial commit
This commit is contained in:
Zhongwei Li
514
references/kubernetes-operator.md
Normal file
514
references/kubernetes-operator.md
Normal file
@@ -0,0 +1,514 @@
|
||||
# SAP BTP Service Operator for Kubernetes
|
||||
|
||||
The SAP BTP Service Operator enables Kubernetes clusters to consume SAP BTP services through native Kubernetes resources.
|
||||
|
||||
**GitHub Repository**: [https://github.com/SAP/sap-btp-service-operator](https://github.com/SAP/sap-btp-service-operator)
|
||||
|
||||
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
- [Infrastructure & Tools](#infrastructure--tools)
|
||||
- [Environment Setup](#environment-setup)
|
||||
- [SAP BTP Requirements](#sap-btp-requirements)
|
||||
2. [Setup Process](#setup-process)
|
||||
- [Install cert-manager](#step-1-install-cert-manager)
|
||||
- [Create Service Manager Credentials](#step-2-create-service-manager-credentials)
|
||||
- [Extract Credentials](#step-3-extract-credentials)
|
||||
- [Deploy Operator with Helm](#step-4-deploy-operator-with-helm)
|
||||
3. [Custom Resource Definitions](#custom-resource-definitions)
|
||||
- [ServiceInstance CRD](#serviceinstance-crd)
|
||||
- [ServiceBinding CRD](#servicebinding-crd)
|
||||
4. [Using Credentials in Pods](#using-credentials-in-pods)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [Volume Mount](#volume-mount)
|
||||
5. [Migration from Service Catalog (svcat)](#migration-from-service-catalog-svcat)
|
||||
- [Prerequisites](#prerequisites-1)
|
||||
- [Step 1: Prepare Platform](#step-1-prepare-platform)
|
||||
- [Step 2: Install Migration CLI](#step-2-install-migration-cli)
|
||||
- [Step 3: Dry Run Migration](#step-3-dry-run-migration)
|
||||
- [Step 4: Execute Migration](#step-4-execute-migration)
|
||||
- [Migration Process](#migration-process)
|
||||
- [Important Notes](#important-notes)
|
||||
6. [Troubleshooting](#troubleshooting)
|
||||
- [Operator Not Starting](#operator-not-starting)
|
||||
- [Instance Creation Fails](#instance-creation-fails)
|
||||
- [Binding Creation Fails](#binding-creation-fails)
|
||||
- [Secret Not Created](#secret-not-created)
|
||||
7. [Best Practices](#best-practices)
|
||||
8. [Documentation Links](#documentation-links)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Infrastructure & Tools
|
||||
|
||||
| Requirement | Version | Purpose |
|
||||
|-------------|---------|---------|
|
||||
| Kubernetes cluster | - | Target deployment |
|
||||
| kubectl | 1.7+ | Cluster management |
|
||||
| Helm | 3.1.2+ | Operator deployment |
|
||||
| SMCTL | 1.10.1+ | Service Manager CLI |
|
||||
|
||||
### Environment Setup
|
||||
|
||||
```bash
|
||||
# Configure kubeconfig
|
||||
export KUBECONFIG='/path/to/kubeconfig.yaml'
|
||||
|
||||
# Verify kubectl
|
||||
kubectl version --client
|
||||
|
||||
# Verify Helm
|
||||
helm version
|
||||
```
|
||||
|
||||
### SAP BTP Requirements
|
||||
|
||||
- Active SAP Service Manager subscription
|
||||
- Subaccount Service Administrator role
|
||||
- Access to SAP BTP cockpit or SMCTL
|
||||
|
||||
---
|
||||
|
||||
## Setup Process
|
||||
|
||||
### Step 1: Install cert-manager
|
||||
|
||||
cert-manager handles TLS certificates for operator communication.
|
||||
|
||||
```bash
|
||||
# Install cert-manager
|
||||
kubectl apply -f [https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml](https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml)
|
||||
|
||||
# Verify installation
|
||||
kubectl get pods -n cert-manager
|
||||
```
|
||||
|
||||
Wait for all cert-manager pods to be Running.
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Create Service Manager Credentials
|
||||
|
||||
**Option A: Using SMCTL**
|
||||
|
||||
```bash
|
||||
# Login to Service Manager
|
||||
smctl login -a [https://service-manager.cfapps.<region>.hana.ondemand.com](https://service-manager.cfapps.<region>.hana.ondemand.com) \
|
||||
--param subdomain=<subdomain>
|
||||
|
||||
# Create instance with service-operator-access plan
|
||||
smctl provision sm-operator service-manager service-operator-access --mode sync
|
||||
|
||||
# Create binding
|
||||
smctl bind sm-operator sm-operator-binding --mode sync
|
||||
|
||||
# Get credentials
|
||||
smctl get-binding sm-operator-binding -o json
|
||||
```
|
||||
|
||||
**Option B: Using BTP Cockpit**
|
||||
|
||||
1. Navigate to Services > Service Marketplace
|
||||
2. Find "Service Manager"
|
||||
3. Create instance with plan "service-operator-access"
|
||||
4. Create binding and download credentials
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Extract Credentials
|
||||
|
||||
From the binding, extract:
|
||||
|
||||
**Default Credentials**:
|
||||
- `clientid`
|
||||
- `clientsecret`
|
||||
- `sm_url`
|
||||
- `url` (UAA URL)
|
||||
|
||||
**X.509 Credentials** (if configured):
|
||||
- `clientid`
|
||||
- `certificate`
|
||||
- `key`
|
||||
- `certurl`
|
||||
- `sm_url`
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Deploy Operator with Helm
|
||||
|
||||
**Using Default Credentials**:
|
||||
|
||||
```bash
|
||||
# Add Helm repository
|
||||
helm repo add sap-btp-operator [https://sap.github.io/sap-btp-service-operator/](https://sap.github.io/sap-btp-service-operator/)
|
||||
helm repo update
|
||||
|
||||
# Install operator
|
||||
helm install sap-btp-operator sap-btp-operator/sap-btp-operator \
|
||||
--namespace sap-btp-operator \
|
||||
--create-namespace \
|
||||
--set manager.secret.clientid=<clientid> \
|
||||
--set manager.secret.clientsecret=<clientsecret> \
|
||||
--set manager.secret.sm_url=<sm_url> \
|
||||
--set manager.secret.tokenurl=<url>/oauth/token
|
||||
```
|
||||
|
||||
**Using X.509 Credentials**:
|
||||
|
||||
```bash
|
||||
helm install sap-btp-operator sap-btp-operator/sap-btp-operator \
|
||||
--namespace sap-btp-operator \
|
||||
--create-namespace \
|
||||
--set manager.secret.clientid=<clientid> \
|
||||
--set manager.secret.tls.crt="$(cat cert.pem)" \
|
||||
--set manager.secret.tls.key="$(cat key.pem)" \
|
||||
--set manager.secret.sm_url=<sm_url> \
|
||||
--set manager.secret.tokenurl=<certurl>/oauth/token
|
||||
```
|
||||
|
||||
**Verify Installation**:
|
||||
|
||||
```bash
|
||||
kubectl get pods -n sap-btp-operator
|
||||
kubectl get crds | grep services.cloud.sap.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Resource Definitions
|
||||
|
||||
### ServiceInstance CRD
|
||||
|
||||
**apiVersion**: `services.cloud.sap.com/v1alpha1`
|
||||
**kind**: `ServiceInstance`
|
||||
|
||||
**Full Specification**:
|
||||
|
||||
```yaml
|
||||
apiVersion: services.cloud.sap.com/v1alpha1
|
||||
kind: ServiceInstance
|
||||
metadata:
|
||||
name: my-service-instance
|
||||
namespace: default
|
||||
labels:
|
||||
app: my-app
|
||||
spec:
|
||||
# Required: Service offering name from marketplace
|
||||
serviceOfferingName: xsuaa
|
||||
|
||||
# Required: Service plan name
|
||||
servicePlanName: application
|
||||
|
||||
# Optional: External name (appears in BTP cockpit)
|
||||
externalName: my-instance-external-name
|
||||
|
||||
# Optional: Service-specific parameters
|
||||
parameters:
|
||||
xsappname: my-app
|
||||
tenant-mode: dedicated
|
||||
scopes:
|
||||
- name: read
|
||||
description: Read access
|
||||
role-templates:
|
||||
- name: Viewer
|
||||
scope-references:
|
||||
- read
|
||||
|
||||
# Optional: Reference to secret containing parameters
|
||||
parametersFrom:
|
||||
- secretKeyRef:
|
||||
name: my-params-secret
|
||||
key: parameters
|
||||
|
||||
# Optional: Custom tags
|
||||
customTags:
|
||||
- environment:production
|
||||
- team:platform
|
||||
```
|
||||
|
||||
**Create Instance**:
|
||||
|
||||
```bash
|
||||
kubectl apply -f service-instance.yaml
|
||||
```
|
||||
|
||||
**Check Status**:
|
||||
|
||||
```bash
|
||||
kubectl get serviceinstances
|
||||
kubectl describe serviceinstance my-service-instance
|
||||
```
|
||||
|
||||
**Status Conditions**:
|
||||
- `Ready`: Instance is ready for use
|
||||
- `Failed`: Provisioning failed
|
||||
|
||||
---
|
||||
|
||||
### ServiceBinding CRD
|
||||
|
||||
**apiVersion**: `services.cloud.sap.com/v1alpha1`
|
||||
**kind**: `ServiceBinding`
|
||||
|
||||
**Full Specification**:
|
||||
|
||||
```yaml
|
||||
apiVersion: services.cloud.sap.com/v1alpha1
|
||||
kind: ServiceBinding
|
||||
metadata:
|
||||
name: my-binding
|
||||
namespace: default
|
||||
spec:
|
||||
# Required: Reference to ServiceInstance
|
||||
serviceInstanceName: my-service-instance
|
||||
|
||||
# Optional: External name
|
||||
externalName: my-binding-external
|
||||
|
||||
# Optional: Binding parameters
|
||||
parameters:
|
||||
credential-type: x509
|
||||
key-length: 4096
|
||||
validity-type: MONTHS
|
||||
validity: 6
|
||||
|
||||
# Optional: Reference to secret containing parameters
|
||||
parametersFrom:
|
||||
- secretKeyRef:
|
||||
name: binding-params
|
||||
key: parameters
|
||||
|
||||
# Optional: Name of secret to create (defaults to binding name)
|
||||
secretName: my-binding-secret
|
||||
|
||||
# Optional: Secret template for custom formatting
|
||||
secretKey: credentials.json
|
||||
|
||||
# Optional: Root key in secret
|
||||
secretRootKey: credentials
|
||||
```
|
||||
|
||||
**Create Binding**:
|
||||
|
||||
```bash
|
||||
kubectl apply -f service-binding.yaml
|
||||
```
|
||||
|
||||
**Check Status**:
|
||||
|
||||
```bash
|
||||
kubectl get servicebindings
|
||||
kubectl describe servicebinding my-binding
|
||||
```
|
||||
|
||||
**Access Credentials**:
|
||||
|
||||
```bash
|
||||
# Credentials stored in Kubernetes secret
|
||||
kubectl get secret my-binding -o yaml
|
||||
|
||||
# Decode credentials
|
||||
kubectl get secret my-binding -o jsonpath='{.data.clientid}' | base64 -d
|
||||
kubectl get secret my-binding -o jsonpath='{.data.clientsecret}' | base64 -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Credentials in Pods
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: my-app
|
||||
spec:
|
||||
containers:
|
||||
- name: app
|
||||
image: my-app:latest
|
||||
env:
|
||||
- name: XSUAA_CLIENTID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: my-binding
|
||||
key: clientid
|
||||
- name: XSUAA_CLIENTSECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: my-binding
|
||||
key: clientsecret
|
||||
- name: XSUAA_URL
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: my-binding
|
||||
key: url
|
||||
```
|
||||
|
||||
### Volume Mount
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: my-app
|
||||
spec:
|
||||
containers:
|
||||
- name: app
|
||||
image: my-app:latest
|
||||
volumeMounts:
|
||||
- name: credentials
|
||||
mountPath: /etc/secrets
|
||||
readOnly: true
|
||||
volumes:
|
||||
- name: credentials
|
||||
secret:
|
||||
secretName: my-binding
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration from Service Catalog (svcat)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- SMCTL CLI installed
|
||||
- Service Catalog (svcat) currently deployed
|
||||
- Access to both svcat and SAP BTP Service Operator
|
||||
|
||||
### Step 1: Prepare Platform
|
||||
|
||||
```bash
|
||||
# Get cluster ID from catalog ConfigMap
|
||||
CLUSTER_ID=$(kubectl get configmap cluster-info -n catalog -o jsonpath='{.data.id}')
|
||||
|
||||
# Prepare platform for migration
|
||||
smctl curl -X PATCH "/v1/platforms/<platformID>" \
|
||||
-d '{"credentials":{"rotatable":true}}' \
|
||||
--param subaccount_id=<subaccount-id>
|
||||
```
|
||||
|
||||
### Step 2: Install Migration CLI
|
||||
|
||||
```bash
|
||||
# From GitHub releases
|
||||
# [https://github.com/SAP/sap-btp-service-operator/releases](https://github.com/SAP/sap-btp-service-operator/releases)
|
||||
|
||||
# Or via Go
|
||||
go install github.com/SAP/sap-btp-service-operator/tools/btpmigrate@latest
|
||||
```
|
||||
|
||||
### Step 3: Dry Run Migration
|
||||
|
||||
```bash
|
||||
# Test migration without making changes
|
||||
btpmigrate --dry-run
|
||||
```
|
||||
|
||||
Review any errors before proceeding.
|
||||
|
||||
### Step 4: Execute Migration
|
||||
|
||||
```bash
|
||||
# Perform actual migration
|
||||
btpmigrate
|
||||
```
|
||||
|
||||
### Migration Process
|
||||
|
||||
1. **Scanning**: Fetches all instances/bindings from svcat and BTP
|
||||
2. **Validation**: Verifies each resource can be migrated
|
||||
3. **Migration**: Removes from svcat, adds to BTP operator
|
||||
|
||||
### Important Notes
|
||||
|
||||
- Platform becomes suspended during migration
|
||||
- Reversible until actual migration starts
|
||||
- Original svcat platform unusable after migration
|
||||
- Test in non-production first
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Operator Not Starting
|
||||
|
||||
```bash
|
||||
# Check operator pods
|
||||
kubectl get pods -n sap-btp-operator
|
||||
|
||||
# Check operator logs
|
||||
kubectl logs -n sap-btp-operator deployment/sap-btp-operator-controller-manager
|
||||
|
||||
# Verify cert-manager
|
||||
kubectl get pods -n cert-manager
|
||||
```
|
||||
|
||||
### Instance Creation Fails
|
||||
|
||||
```bash
|
||||
# Check instance status
|
||||
kubectl describe serviceinstance <name>
|
||||
|
||||
# Look for events
|
||||
kubectl get events --field-selector involvedObject.name=<instance-name>
|
||||
```
|
||||
|
||||
**Common Issues**:
|
||||
- Service not entitled in subaccount
|
||||
- Invalid parameters
|
||||
- Plan not available in region
|
||||
- Quota exceeded
|
||||
|
||||
### Binding Creation Fails
|
||||
|
||||
```bash
|
||||
# Check binding status
|
||||
kubectl describe servicebinding <name>
|
||||
|
||||
# Verify instance is ready
|
||||
kubectl get serviceinstance <instance-name>
|
||||
```
|
||||
|
||||
**Common Issues**:
|
||||
- Referenced instance not ready
|
||||
- Instance doesn't support bindings
|
||||
- Invalid binding parameters
|
||||
|
||||
### Secret Not Created
|
||||
|
||||
```bash
|
||||
# Check binding status
|
||||
kubectl get servicebinding <name> -o yaml
|
||||
|
||||
# Verify secret exists
|
||||
kubectl get secrets | grep <binding-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Namespace Organization**: Group related services in namespaces
|
||||
2. **Labels**: Use labels for filtering and organization
|
||||
3. **External Names**: Use descriptive external names for cockpit visibility
|
||||
4. **Parameters in Secrets**: Store sensitive parameters in Kubernetes secrets
|
||||
5. **Resource Limits**: Set appropriate limits on operator deployment
|
||||
6. **Monitoring**: Monitor operator health and CRD status
|
||||
7. **Backup**: Document all ServiceInstance/ServiceBinding manifests
|
||||
|
||||
---
|
||||
|
||||
## Documentation Links
|
||||
|
||||
- **Setup**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/setup-e977f23.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/setup-e977f23.md)
|
||||
- **Prerequisites**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/prerequisites-dd5faaa.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/prerequisites-dd5faaa.md)
|
||||
- **Working with Operator**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/working-with-sap-btp-service-operator-0ccebd7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/working-with-sap-btp-service-operator-0ccebd7.md)
|
||||
- **Migration**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/migrating-from-svcat-to-sap-btp-service-ec7f5c7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/migrating-from-svcat-to-sap-btp-service-ec7f5c7.md)
|
||||
- **GitHub Repository**: [https://github.com/SAP/sap-btp-service-operator](https://github.com/SAP/sap-btp-service-operator)
|
||||
Reference in New Issue
Block a user