zhongwei/gh-secondsky-sap-skills-skills-sap-btp-service-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:55:15 +08:00
commit 0e7a2dc56e
16 changed files with 4431 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

402
references/api-reference.md Normal file
View File

@@ -0,0 +1,402 @@
# SAP Service Manager API Reference
**Base URI**: `[https://service-manager.cfapps.<region>.hana.ondemand.com/v1/`](https://service-manager.cfapps.<region>.hana.ondemand.com/v1/`)
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
---
## Table of Contents
1. [Authentication](#authentication)
- User Access Tokens
- Client Access Tokens
- Token Retrieval
2. [API Groups](#api-groups)
- [Platforms API](#1-platforms-api)
- [Service Brokers API](#2-service-brokers-api)
- [Service Offerings API](#3-service-offerings-api)
- [Service Plans API](#4-service-plans-api)
- [Service Instances API](#5-service-instances-api)
- [Service Bindings API](#6-service-bindings-api)
- [Operations API](#7-operations-api)
3. [Common Patterns](#common-patterns)
- Filtering
- Pagination
- Error Handling
4. [Response Formats](#response-formats)
- Success Responses
- Error Responses
5. [Rate Limiting](#rate-limiting)
- Limits Overview
- Headers
---
## Authentication
### User Access Tokens
- Represent named users
- Scopes derived from assigned roles
- Obtained via password or SSO flow
### Client Access Tokens
- Represent technical clients
- Scopes derived from service plan
- Obtained via client credentials flow
### Token Retrieval
```bash
curl '<uaa_url>/oauth/token' -X POST \
-H 'Accept: application/json' \
-d 'grant_type=client_credentials&client_id=<clientid>&client_secret=<clientsecret>'
```
**Response**:
```json
{
"access_token": "<access_token>",
"token_type": "bearer",
"expires_in": 43199,
"scope": "<xsappname>.job.read <xsappname>.event.read"
}
```
**Usage**: Include `Authorization: Bearer <access_token>` header in all requests.
---
## API Groups
### 1. Platforms API
**Base**: `/v1/platforms`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/platforms` | List all registered platforms |
| GET | `/v1/platforms/{platformID}` | Get specific platform |
| POST | `/v1/platforms` | Register new platform |
| PATCH | `/v1/platforms/{platformID}` | Update platform |
| DELETE | `/v1/platforms/{platformID}` | Unregister platform |
**Platform Registration Request**:
```json
{
"name": "my-platform",
"type": "kubernetes",
"description": "My K8s cluster"
}
```
**Platform Response**:
```json
{
"id": "platform-id",
"name": "my-platform",
"type": "kubernetes",
"description": "My K8s cluster",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z",
"credentials": {
"basic": {
"username": "generated-user",
"password": "generated-pass"
}
}
}
```
---
### 2. Service Brokers API
**Base**: `/v1/service_brokers`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/service_brokers` | List all brokers |
| GET | `/v1/service_brokers/{brokerID}` | Get specific broker |
| POST | `/v1/service_brokers` | Register broker |
| PATCH | `/v1/service_brokers/{brokerID}` | Update broker |
| DELETE | `/v1/service_brokers/{brokerID}` | Delete broker |
**Broker Registration Request**:
```json
{
"name": "my-broker",
"broker_url": "[https://broker.example.com",](https://broker.example.com",)
"description": "My service broker",
"credentials": {
"basic": {
"username": "broker-user",
"password": "broker-pass"
}
}
}
```
---
### 3. Service Instances API
**Base**: `/v1/service_instances`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/service_instances` | List all instances |
| GET | `/v1/service_instances/{instanceID}` | Get specific instance |
| POST | `/v1/service_instances` | Create instance |
| PATCH | `/v1/service_instances/{instanceID}` | Update instance |
| DELETE | `/v1/service_instances/{instanceID}` | Delete instance |
**Create Instance Request**:
```json
{
"name": "my-instance",
"service_plan_id": "plan-guid",
"parameters": {
"key1": "value1"
},
"labels": {
"environment": ["production"]
}
}
```
**Instance Response**:
```json
{
"id": "instance-id",
"name": "my-instance",
"service_plan_id": "plan-guid",
"platform_id": "platform-id",
"context": {},
"parameters": {},
"labels": {},
"ready": true,
"usable": true,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z",
"last_operation": {
"type": "create",
"state": "succeeded"
}
}
```
**Query Parameters**:
- `fieldQuery`: Filter by field values
- `labelQuery`: Filter by label values
- `max_items`: Limit results
- `token`: Pagination token
---
### 4. Service Bindings API
**Base**: `/v1/service_bindings`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/service_bindings` | List all bindings |
| GET | `/v1/service_bindings/{bindingID}` | Get specific binding |
| POST | `/v1/service_bindings` | Create binding |
| DELETE | `/v1/service_bindings/{bindingID}` | Delete binding |
**Create Binding Request**:
```json
{
"name": "my-binding",
"service_instance_id": "instance-id",
"parameters": {
"credential-type": "x509"
}
}
```
**Binding Response** (Default Credentials):
```json
{
"id": "binding-id",
"name": "my-binding",
"service_instance_id": "instance-id",
"credentials": {
"clientid": "client-id",
"clientsecret": "client-secret",
"url": "[https://service.example.com",](https://service.example.com",)
"sm_url": "[https://service-manager.cfapps.region.hana.ondemand.com"](https://service-manager.cfapps.region.hana.ondemand.com")
},
"ready": true,
"created_at": "2025-01-01T00:00:00Z"
}
```
**Binding Response** (X.509 Credentials):
```json
{
"credentials": {
"clientid": "client-id",
"certificate": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"certurl": "[https://cert.auth.url"](https://cert.auth.url")
}
}
```
---
### 5. Service Plans API
**Base**: `/v1/service_plans`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/service_plans` | List all plans |
| GET | `/v1/service_plans/{planID}` | Get specific plan |
**Plan Response**:
```json
{
"id": "plan-id",
"name": "subaccount-admin",
"description": "Full administrative access",
"free": false,
"bindable": true,
"service_offering_id": "offering-id",
"catalog_id": "catalog-id",
"catalog_name": "subaccount-admin",
"metadata": {}
}
```
---
### 6. Service Offerings API
**Base**: `/v1/service_offerings`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/service_offerings` | List all offerings |
| GET | `/v1/service_offerings/{offeringID}` | Get specific offering |
**Offering Response**:
```json
{
"id": "offering-id",
"name": "service-manager",
"description": "SAP Service Manager",
"bindable": true,
"broker_id": "broker-id",
"catalog_id": "catalog-id",
"catalog_name": "service-manager"
}
```
---
### 7. Operations API
**Base**: `/v1/{resourceType}/{resourceID}/operations`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/{type}/{id}/operations/{opID}` | Get operation status |
**Path Parameters**:
- `resourceType`: `platforms`, `service_brokers`, `service_bindings`, `service_instances`
- `resourceID`: Resource identifier
- `operationID`: Operation identifier
**Operation Response**:
```json
{
"id": "operation-id",
"type": "create",
"state": "in progress",
"resource_id": "resource-id",
"resource_type": "service_instances",
"description": "Provisioning service instance",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
```
**Operation States**:
- `in progress` - Operation running
- `succeeded` - Operation completed successfully
- `failed` - Operation failed
---
## HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async operation started) |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (invalid/missing token) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not found |
| 409 | Conflict (resource already exists) |
| 422 | Unprocessable entity |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
---
## Async Operations
POST, PATCH, and DELETE operations on instances and bindings are async by default.
**Response** (202 Accepted):
```json
{
"id": "resource-id",
"last_operation": {
"type": "create",
"state": "in progress"
}
}
```
**Headers**:
- `Location`: `/v1/service_instances/{id}/operations/{opId}` - Poll this URL
**Polling**:
```bash
# Initial request
POST /v1/service_instances
# Response: 202 with Location header
# Poll status
GET /v1/service_instances/{id}/operations/{opId}
# Repeat until state is "succeeded" or "failed"
```
---
## Swagger UI
Access interactive API documentation:
`[https://service-manager.cfapps.<region>.hana.ondemand.com/swaggerui/swagger-ui.html`](https://service-manager.cfapps.<region>.hana.ondemand.com/swaggerui/swagger-ui.html`)
**Example Regions**:
- EU10 (Frankfurt): `eu10.hana.ondemand.com`
- US10 (US East): `us10.hana.ondemand.com`
- AP10 (Australia): `ap10.hana.ondemand.com`
---
## Documentation Links
- **API Groups**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-api-groups-9b97aee.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-api-groups-9b97aee.md)
- **Service Instances**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/instances-23af00d.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/instances-23af00d.md)
- **Service Bindings**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/service-bindings-392eb36.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/service-bindings-392eb36.md)
- **Platforms**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md)
- **Brokers**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/brokers-743f3f7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/brokers-743f3f7.md)

591
references/btp-cli-commands.md Normal file
View File

@@ -0,0 +1,591 @@
# BTP CLI Service Manager Commands
The SAP BTP CLI (`btp`) provides service management commands as an alternative to SMCTL.
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
---
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Service Instance Commands](#service-instance-commands)
- [btp create services/instance](#btp-create-servicesinstance)
- [btp get services/instance](#btp-get-servicesinstance)
- [btp list services/instances](#btp-list-servicesinstances)
- [btp delete services/instance](#btp-delete-servicesinstance)
- [btp update services/instance](#btp-update-servicesinstance)
3. [Service Binding Commands](#service-binding-commands)
- [btp create services/binding](#btp-create-servicesbinding)
- [btp get services/binding](#btp-get-servicesbinding)
- [btp list services/bindings](#btp-list-servicesbindings)
- [btp delete services/binding](#btp-delete-servicesbinding)
4. [Platform Commands](#platform-commands)
- [btp list services/platform](#btp-list-servicesplatform)
- [btp register services/platform](#btp-register-servicesplatform)
- [btp unregister services/platform](#btp-unregister-servicesplatform)
- [btp get services/platform](#btp-get-servicesplatform)
5. [Marketplace Commands](#marketplace-commands)
- [btp list services/offering](#btp-list-servicesoffering)
- [btp list services/plan](#btp-list-servicesplan)
6. [Common Examples](#common-examples)
7. [Migration from SMCTL](#migration-from-smctl)
---
## Prerequisites
1. Install BTP CLI: [https://tools.hana.ondemand.com/#cloud](https://tools.hana.ondemand.com/#cloud)
2. Login: `btp login`
3. Set target: `btp target --subaccount <subaccount-id>`
---
## Service Instance Commands
### btp create services/instance
Create a new service instance.
**Syntax**:
```bash
btp create services/instance [parameters]
```
**Required Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID (skip if target set) |
| `-s, --service <name>` | Service name |
| `-p, --plan <id>` | Service plan ID |
**Optional Parameters**:
| Parameter | Description |
|-----------|-------------|
| `--parameters <json>` | JSON configuration |
| `-l, --labels <json>` | Labels as JSON |
**Label Format**:
```json
{"<label_name>": ["<label_value>"]}
```
- Keys: max 100 chars, alphanumeric + `.` `_` `-`
- Values: arrays of unique strings, max 255 chars each
**Examples**:
```bash
# Basic creation
btp create services/instance \
--subaccount abc-123 \
--service xsuaa \
--plan application
# With parameters
btp create services/instance \
--subaccount abc-123 \
--service hana \
--plan hdi-shared \
--parameters '{"database_id":"db-123"}'
# With labels
btp create services/instance \
--subaccount abc-123 \
--service xsuaa \
--plan application \
--labels '{"environment":["production"],"team":["platform"]}'
```
---
### btp get services/instance
Get details of a service instance.
**Syntax**:
```bash
btp get services/instance <instance-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<instance-id>` | Service instance ID |
| `-sa, --subaccount <id>` | Subaccount ID |
| `--show-parameters` | Display configuration parameters |
**Example**:
```bash
btp get services/instance inst-123 \
--subaccount abc-123 \
--show-parameters
```
---
### btp list services/instance
List all service instances.
**Syntax**:
```bash
btp list services/instance [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--labels-filter <query>` | Filter by labels (e.g., `landscape eq 'production'`) |
| `--fields-filter <query>` | Filter by fields (e.g., `usable eq 'true'`) |
**Example**:
```bash
btp list services/instance --subaccount abc-123 --fields-filter "ready eq 'true'"
```
---
### btp update services/instance
Update a service instance.
**Syntax**:
```bash
btp update services/instance [parameters]
```
**Required Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID (skip if target set) |
| `-s, --service` or `-n, --name <name>` | Service instance name |
| `-id <id>` | Service instance ID |
**Optional Parameters**:
| Parameter | Description |
|-----------|-------------|
| `--new-name <name>` | New name for the instance |
| `-p, --plan <id>` | New service plan ID |
| `--plan-name <name>` | New service plan name |
| `--parameters <json>` | New parameters as JSON |
| `-l, --labels <json>` | New labels |
**Note**: Plan updates only available if additional plans exist and are entitled.
---
### btp delete services/instance
Delete a service instance.
**Syntax**:
```bash
btp delete services/instance <instance-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<instance-id>` | Service instance ID |
| `-sa, --subaccount <id>` | Subaccount ID |
| `--confirm` | Skip confirmation |
---
## Service Binding Commands
### btp create services/binding
Create a service binding.
**Syntax**:
```bash
btp create services/binding [parameters]
```
**Required Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `-b, --binding <name>` or `-n, --name <name>` | Binding name |
| `-si, --service-instance <id>` or `--instance-name <name>` | Service instance |
**Optional Parameters**:
| Parameter | Description |
|-----------|-------------|
| `--parameters <json>` | Binding parameters |
| `-l, --labels <json>` | Labels |
**Examples**:
```bash
# Basic binding
btp create services/binding \
--subaccount abc-123 \
--binding my-binding \
--service-instance inst-123
# With X.509 credentials
btp create services/binding \
--subaccount abc-123 \
--name my-binding \
--instance-name my-instance \
--parameters '{"credential-type":"x509"}'
```
---
### btp get services/binding
Get binding details.
**Syntax**:
```bash
btp get services/binding <binding-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<binding-id>` | Binding ID |
| `-sa, --subaccount <id>` | Subaccount ID |
| `--show-parameters` | Display parameters |
---
### btp list services/binding
List all bindings.
**Syntax**:
```bash
btp list services/binding [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--labels-filter <query>` | Filter by labels (e.g., `purpose eq 'backing services'`) |
| `--fields-filter <query>` | Filter by fields (e.g., `ready eq 'true'`) |
---
### btp delete services/binding
Delete a binding.
**Syntax**:
```bash
btp delete services/binding <binding-id> [parameters]
```
---
## Platform Commands
### btp list services/platform
List all registered platforms.
**Syntax**:
```bash
btp list services/platform [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--labels-filter <query>` | Filter by labels |
| `--fields-filter <query>` | Filter by fields |
---
### btp get services/platform
Get platform details.
**Syntax**:
```bash
btp get services/platform <platform-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<platform-id>` | Platform ID |
| `-sa, --subaccount <id>` | Subaccount ID |
**Output**: ID, Name, Type, Description, URL, Created, Updated, Labels
---
### btp register services/platform
Register a new platform (Kubernetes only).
**Syntax**:
```bash
btp register services/platform [parameters]
```
**Required Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `-n, --name <name>` | Platform name (alphanumeric + hyphens, must be unique) |
| `-t, --type <type>` | Platform type (only `kubernetes` supported) |
**Optional Parameters**:
| Parameter | Description |
|-----------|-------------|
| `--id <id>` | Custom platform ID (globally unique) |
| `-d, --description <desc>` | Description |
| `-l, --labels <json>` | Labels as JSON |
**Example**:
```bash
btp register services/platform \
--subaccount abc-123 \
--name my-k8s \
--type kubernetes \
--description "Production cluster"
```
**Output**: Platform credentials (username/password) returned on success.
---
### btp update services/platform
Update a platform.
**Syntax**:
```bash
btp update services/platform <platform-id> [parameters]
```
---
### btp unregister services/platform
Unregister a platform.
**Syntax**:
```bash
btp unregister services/platform <platform-id> --subaccount <id>
```
---
## Broker Commands
### btp list services/broker
List all registered brokers.
**Syntax**:
```bash
btp list services/broker [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--labels-filter <query>` | Filter by labels |
| `--fields-filter <query>` | Filter by fields |
**Output**: ID, Name, Description, Broker URL, Created, Updated, Labels
---
### btp get services/broker
Get broker details.
**Syntax**:
```bash
btp get services/broker <broker-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<broker-id>` | Broker ID |
| `-sa, --subaccount <id>` | Subaccount ID |
**Output**: ID, Name, Description, Broker URL, Created, Updated, Labels
---
### btp register services/broker
Register a service broker.
**Syntax**:
```bash
btp register services/broker [parameters]
```
**Required Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `-n, --name <name>` | Broker name (alphanumeric + hyphens, must be unique) |
| `--url <url>` | Broker URL |
| `-u, --user <user>` | Auth username |
| `-p, --password <pass>` | Auth password |
**Optional Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-d, --description <desc>` | Description |
| `-l, --labels <json>` | Labels as JSON |
**Label Format**:
- Keys: max 100 chars, alphanumeric + `.` `_` `-`
- Values: arrays of strings, max 255 chars each, no newlines
---
### btp unregister services/broker
Unregister a broker.
**Syntax**:
```bash
btp unregister services/broker <broker-id> --subaccount <id>
```
---
## Offering Commands
### btp list services/offering
List available service offerings.
**Syntax**:
```bash
btp list services/offering [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--environment <env>` | Filter by environment: `cloudfoundry` or `kubernetes` |
| `--labels-filter <query>` | Filter by labels (e.g., `environment eq 'test'`) |
| `--fields-filter <query>` | Filter by fields |
**Note**: Without `--environment`, returns services consumable through Service Manager bindings.
---
### btp get services/offering
Get offering details.
**Syntax**:
```bash
btp get services/offering <offering-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<offering-id>` | Offering ID |
| `-sa, --subaccount <id>` | Subaccount ID |
---
## Plan Commands
### btp list services/plan
List available service plans.
**Syntax**:
```bash
btp list services/plan [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `-sa, --subaccount <id>` | Subaccount ID |
| `--environment <env>` | Filter by environment: `cloudfoundry` or `kubernetes` |
| `--labels-filter <query>` | Filter by labels |
| `--fields-filter <query>` | Filter by fields |
---
### btp get services/plan
Get plan details.
**Syntax**:
```bash
btp get services/plan <plan-id> [parameters]
```
**Parameters**:
| Parameter | Description |
|-----------|-------------|
| `<plan-id>` | Plan ID |
| `-sa, --subaccount <id>` | Subaccount ID |
---
## Common Patterns
### Set Target (Skip Subaccount on Each Command)
```bash
# Set target once
btp target --subaccount abc-123
# Now commands don't need --subaccount
btp list services/instance
btp create services/instance --service xsuaa --plan application
```
### JSON Output
```bash
btp --format json list services/instance
```
### Parameters from File
```bash
btp create services/instance \
--service hana \
--plan hdi-shared \
--parameters @params.json
```
---
## SMCTL vs BTP CLI Comparison
| Operation | SMCTL | BTP CLI |
|-----------|-------|---------|
| Login | `smctl login` | `btp login` |
| Create instance | `smctl provision` | `btp create services/instance` |
| Delete instance | `smctl deprovision` | `btp delete services/instance` |
| Create binding | `smctl bind` | `btp create services/binding` |
| List instances | `smctl list-instances` | `btp list services/instance` |
| Marketplace | `smctl marketplace` | `btp list services/offering` |
**Recommendation**: Use SMCTL for Service Manager-specific operations; use BTP CLI for unified BTP management.
---
## Documentation Links
- **Create Instance**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/create-services-instance-5a44ad8.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/create-services-instance-5a44ad8.md)
- **Create Binding**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/create-services-binding-7cf9dc5.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/create-services-binding-7cf9dc5.md)
- **Get Instance**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-services-instance-adb4c54.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-services-instance-adb4c54.md)
- **Platform Commands**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md)

514
references/kubernetes-operator.md Normal file
View 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)

360
references/rate-limiting-filtering.md Normal file
View File

@@ -0,0 +1,360 @@
# Rate Limiting and Filtering Reference
Complete reference for SAP Service Manager API rate limits and query filtering.
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
---
## Table of Contents
1. [Rate Limiting](#rate-limiting)
- [Identification](#identification)
- [Level 1: All APIs Combined](#level-1-all-apis-combined)
- [Level 2: Resource-Specific Limits](#level-2-resource-specific-limits)
- [Level 3: Instance Operations](#level-3-instance-operations)
- [HTTP 429 Responses](#http-429-responses)
2. [Query Filtering](#query-filtering)
- [Field Filtering](#field-filtering)
- [Label Filtering](#label-filtering)
- [Operators](#operators)
- [Combining Filters](#combining-filters)
3. [Best Practices](#best-practices)
- [Rate Limit Handling](#rate-limit-handling)
- [Filter Optimization](#filter-optimization)
4. [Examples](#examples)
- [Common Query Patterns](#common-query-patterns)
- [Rate Limit Scenarios](#rate-limit-scenarios)
---
## Rate Limiting
SAP Service Manager implements **three concurrent rate limiting levels**. Exceeding any tier triggers throttling, even if other allowances remain.
### Identification
Callers identified by:
- Username (for user tokens)
- OAuth Client ID (for client tokens)
### Level 1: All APIs Combined
| Limit Type | Value |
|------------|-------|
| Per Hour | 10,000 requests |
| Per Minute | 1,000 requests |
Applies to all API endpoints combined.
---
### Level 2: Resource-Specific Limits
| Endpoint | Per Hour | Per Minute |
|----------|----------|------------|
| `/v1/service_bindings` | 6,000 | 600 |
| `/v1/service_offerings` | 1,000 | 100 |
| `/v1/service_plans` | 1,000 | 100 |
---
### Level 3: Method-Specific Limits
| Operation | Endpoint | Per Hour | Per Minute |
|-----------|----------|----------|------------|
| CREATE | `/v1/service_instances` | - | 50 |
| UPDATE | `/v1/service_instances` | 6,000 | 600 |
| DELETE | `/v1/service_instances` | 6,000 | 600 |
**Note**: CREATE has a stricter minute limit (50/min) to prevent provisioning storms.
---
### Rate Limit Error Response
**HTTP Status**: `429 Too Many Requests`
**Response Headers**:
| Header | Description |
|--------|-------------|
| `Retry-After` | When to retry (HTTP-date format) |
**HTTP-date Format**: `Sun, 06 Nov 1994 08:49:37 GMT`
**Example Response**:
```json
{
"error": "rate_limit_exceeded",
"description": "Request rate limit exceeded. Please retry after the time specified in the Retry-After header."
}
```
---
### Best Practices for Rate Limits
1. **Implement Exponential Backoff**:
```javascript
async function withRetry(fn, maxRetries = 5) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.status === 429) {
const retryAfter = error.headers['retry-after'];
const waitTime = retryAfter ?
new Date(retryAfter) - Date.now() :
Math.pow(2, i) * 1000;
await sleep(waitTime);
} else {
throw error;
}
}
}
}
```
2. **Batch Operations**: Group related operations where possible
3. **Cache Responses**: Cache listing responses (offerings, plans)
4. **Stagger Requests**: Distribute requests over time
5. **Monitor Usage**: Track request counts to stay within limits
---
## Filtering
The SAP Service Manager APIs support filtering via query parameters on GET (list) endpoints.
### Query Parameter Types
| Parameter | Purpose | Example |
|-----------|---------|---------|
| `fieldQuery` | Filter by field values | `type eq 'kubernetes'` |
| `labelQuery` | Filter by label values | `environment eq 'dev'` |
Both can be combined; results must match both criteria.
---
### Supported Literal Types
| Type | Format | Example |
|------|--------|---------|
| String | Single quotes | `'my-value'` |
| Boolean | Unquoted | `true`, `false` |
| Integer | Digits with optional sign | `42`, `-7`, `+100` |
| Date-time | ISO 8601 | `2025-01-15T10:30:00Z` |
**String Escaping**: Double single quotes for embedded quotes (`'it''s valid'`)
---
### Field Query Operators
#### Universal Operators (Field & Label Queries)
| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equal | `name eq 'my-instance'` |
| `en` | Equal or null | `broker_id en 'abc-123'` |
| `ne` | Not equal | `type ne 'kubernetes'` |
| `in` | In list | `plan_name in ('small','medium')` |
| `notin` | Not in list | `status notin ('failed','pending')` |
| `and` | Logical AND | `type eq 'cf' and ready eq true` |
| `contains` | Substring match | `name contains 'prod'` |
#### Field-Only Operators
| Operator | Description | Example |
|----------|-------------|---------|
| `gt` | Greater than | `created_at gt '2025-01-01T00:00:00Z'` |
| `ge` | Greater than or equal | `version ge 2` |
| `lt` | Less than | `updated_at lt '2025-06-01T00:00:00Z'` |
| `le` | Less than or equal | `retries le 3` |
---
### Filterable Resources
| Resource | Supports fieldQuery | Supports labelQuery |
|----------|---------------------|---------------------|
| Platforms | Yes | Yes |
| Service Brokers | Yes | Yes |
| Service Instances | Yes | Yes |
| Service Bindings | Yes | Yes |
| Service Plans | Yes | No |
| Service Offerings | Yes | No |
---
### Common Field Names
#### Service Instances
| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Instance ID |
| `name` | String | Instance name |
| `service_plan_id` | String | Plan ID |
| `platform_id` | String | Platform ID |
| `ready` | Boolean | Readiness status |
| `usable` | Boolean | Usability status |
| `created_at` | DateTime | Creation timestamp |
| `updated_at` | DateTime | Last update timestamp |
#### Service Bindings
| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Binding ID |
| `name` | String | Binding name |
| `service_instance_id` | String | Associated instance |
| `ready` | Boolean | Readiness status |
| `created_at` | DateTime | Creation timestamp |
#### Platforms
| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Platform ID |
| `name` | String | Platform name |
| `type` | String | Platform type |
---
### Query Examples
#### Single Field Filter
```
GET /v1/service_instances?fieldQuery=ready eq true
```
#### Multiple Conditions (AND)
```
GET /v1/service_instances?fieldQuery=ready eq true and usable eq true
```
#### In List
```
GET /v1/service_instances?fieldQuery=service_plan_id in ('plan-1','plan-2','plan-3')
```
#### Date Range
```
GET /v1/service_instances?fieldQuery=created_at gt '2025-01-01T00:00:00Z' and created_at lt '2025-02-01T00:00:00Z'
```
#### String Contains
```
GET /v1/service_instances?fieldQuery=name contains 'production'
```
#### Label Query
```
GET /v1/service_instances?labelQuery=environment eq 'production'
```
#### Combined Field and Label Query
```
GET /v1/service_instances?fieldQuery=ready eq true&labelQuery=team eq 'platform'
```
#### Complex Query
```
GET /v1/service_instances?fieldQuery=broker_id eq 'abc-123' and plan_name in ('small','medium') and ready eq true&labelQuery=environment eq 'dev'
```
---
### URL Encoding
Special characters must be URL-encoded:
| Character | Encoded |
|-----------|---------|
| Space | `%20` or `+` |
| Single quote | `%27` |
| Comma | `%2C` |
| Colon | `%3A` |
**Example**:
```
# Original
fieldQuery=name eq 'my instance'
# Encoded
fieldQuery=name%20eq%20%27my%20instance%27
```
---
### Pagination
List endpoints support pagination:
| Parameter | Description |
|-----------|-------------|
| `max_items` | Maximum results per page |
| `token` | Continuation token |
**Response**:
```json
{
"items": [...],
"num_items": 50,
"token": "next-page-token"
}
```
**Usage**:
```
GET /v1/service_instances?max_items=50
GET /v1/service_instances?max_items=50&token=<token-from-previous>
```
---
### Syntax Rules
1. **String literals** require single quotes
2. **Boolean literals** must not be quoted
3. **Literals cannot use brackets** (except in `in`/`notin` lists)
4. **Embedded quotes** use double single quotes (`''`)
5. **Whitespace** around operators is optional but recommended
6. **Case sensitivity**: Field names are case-sensitive
---
### Error Handling
**Invalid Query Syntax**:
```json
{
"error": "InvalidQuery",
"description": "Invalid fieldQuery syntax at position 15"
}
```
**Unknown Field**:
```json
{
"error": "InvalidField",
"description": "Field 'invalid_field' is not supported for filtering"
}
```
---
## Documentation Links
- **Rate Limiting**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/rate-limiting-97be679.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/rate-limiting-97be679.md)
- **Filtering**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/filtering-parameters-and-operators-3331c6e.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/filtering-parameters-and-operators-3331c6e.md)

266
references/roles-permissions.md Normal file
View File

@@ -0,0 +1,266 @@
# SAP Service Manager Roles and Permissions
Complete reference for SAP Service Manager plans, roles, and scopes.
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
---
## Table of Contents
1. [Service Manager Plans](#service-manager-plans)
- [subaccount-admin](#1-subaccount-admin)
- [subaccount-audit](#2-subaccount-audit)
- [container](#3-container)
2. [Roles in SAP BTP](#roles-in-sap-btp)
- [Subaccount Service Administrator](#subaccount-service-administrator)
- [Subaccount Service Viewer](#subaccount-service-viewer)
- [Assigning Roles](#assigning-roles)
3. [Scope Reference](#scope-reference)
- [Broker Scopes](#broker-scopes)
- [Platform Scopes](#platform-scopes)
- [Service Instance Scopes](#service-instance-scopes)
- [Service Binding Scopes](#service-binding-scopes)
4. [Best Practices](#best-practices)
- [Choose the Right Plan](#choose-the-right-plan)
- [Principle of Least Privilege](#principle-of-least-privilege)
- [Client vs User Scopes](#client-vs-user-scopes)
---
## Service Manager Plans
Three broker plans with different access levels:
### 1. subaccount-admin
**Purpose**: Full administrative access to manage all resources in a subaccount.
**Use Case**: Administrators who need to create, update, and delete all service resources.
**Scopes** (10 total):
| Scope | Description |
|-------|-------------|
| `subaccount_broker_manage` | Create, update, delete brokers |
| `subaccount_broker_read` | Read broker information |
| `subaccount_platform_manage` | Create, update, delete platforms |
| `subaccount_platform_read` | Read platform information |
| `subaccount_service_instance_manage` | Create, update, delete instances |
| `subaccount_service_instance_read` | Read instance information |
| `subaccount_service_binding_manage` | Create, delete bindings |
| `subaccount_service_binding_read` | Read binding information |
| `subaccount_service_plan_read` | Read service plans |
| `subaccount_service_offering_read` | Read service offerings |
---
### 2. subaccount-audit
**Purpose**: Read-only access for monitoring and auditing.
**Use Case**: Auditors, monitoring systems, and read-only dashboards.
**Scopes** (6 total):
| Scope | Description |
|-------|-------------|
| `subaccount_broker_read` | Read broker information |
| `subaccount_platform_read` | Read platform information |
| `subaccount_service_instance_read` | Read instance information |
| `subaccount_service_binding_read` | Read binding information |
| `subaccount_service_plan_read` | Read service plans |
| `subaccount_service_offering_read` | Read service offerings |
**Note**: No manage/write permissions.
---
### 3. container
**Purpose**: Isolated access scoped to individual service instances.
**Use Case**: Applications that need to manage their own bindings without access to other resources.
**Visibility Rules**:
- Instances created via container credentials are visible from:
- The container instance itself
- Instances of subaccount-* plans
- NOT visible from other container instances
**Scopes** (7 total):
| Scope | Description |
|-------|-------------|
| `container_service_instance_manage` | Manage container-scoped instances |
| `container_service_instance_read` | Read container-scoped instances |
| `container_service_binding_manage` | Manage container-scoped bindings |
| `container_service_binding_read` | Read container-scoped bindings |
| `subaccount_service_plan_read` | Read service plans |
| `subaccount_service_offering_read` | Read service offerings |
| `subaccount_resource_read` | Read subaccount resources |
---
## Role Collections
### Subaccount Service Administrator
**Description**: Full management access to service resources in the subaccount.
**Permissions** (10):
- Manage and read brokers
- Manage and read platforms
- Manage and read service instances
- Manage and read service bindings
- Read service plans
- Read service offerings
**Assignment**:
1. Navigate to subaccount > Security > Trust Configuration
2. Select SAP ID Service
3. Enter user email
4. Click Show Assignments > Add User
5. Assign Role Collection > Subaccount Service Administrator
---
### Subaccount Service Viewer (Feature Set B)
**Description**: Read-only access to service resources.
**Permissions** (6):
- Read brokers
- Read platforms
- Read service instances
- Read service bindings
- Read service plans
- Read service offerings
**Note**: Available only in Feature Set B subaccounts.
---
## Plan Selection Guide
| Scenario | Recommended Plan |
|----------|------------------|
| Administrative automation | subaccount-admin |
| CI/CD pipelines | subaccount-admin |
| Monitoring dashboards | subaccount-audit |
| Security auditing | subaccount-audit |
| Application self-service | container |
| Isolated microservices | container |
---
## Scope Matrix
| Scope | subaccount-admin | subaccount-audit | container |
|-------|------------------|------------------|-----------|
| Broker manage | Yes | No | No |
| Broker read | Yes | Yes | No |
| Platform manage | Yes | No | No |
| Platform read | Yes | Yes | No |
| Instance manage (subaccount) | Yes | No | No |
| Instance manage (container) | No | No | Yes |
| Instance read (subaccount) | Yes | Yes | No |
| Instance read (container) | No | No | Yes |
| Binding manage (subaccount) | Yes | No | No |
| Binding manage (container) | No | No | Yes |
| Binding read (subaccount) | Yes | Yes | No |
| Binding read (container) | No | No | Yes |
| Plan read | Yes | Yes | Yes |
| Offering read | Yes | Yes | Yes |
---
## API Scope Requirements
### Platforms API
| Operation | Required Scope |
|-----------|----------------|
| List platforms | `subaccount_platform_read` |
| Get platform | `subaccount_platform_read` |
| Register platform | `subaccount_platform_manage` |
| Update platform | `subaccount_platform_manage` |
| Delete platform | `subaccount_platform_manage` |
### Brokers API
| Operation | Required Scope |
|-----------|----------------|
| List brokers | `subaccount_broker_read` |
| Get broker | `subaccount_broker_read` |
| Register broker | `subaccount_broker_manage` |
| Update broker | `subaccount_broker_manage` |
| Delete broker | `subaccount_broker_manage` |
### Instances API
| Operation | Required Scope (subaccount) | Required Scope (container) |
|-----------|----------------------------|---------------------------|
| List instances | `subaccount_service_instance_read` | `container_service_instance_read` |
| Get instance | `subaccount_service_instance_read` | `container_service_instance_read` |
| Create instance | `subaccount_service_instance_manage` | `container_service_instance_manage` |
| Update instance | `subaccount_service_instance_manage` | `container_service_instance_manage` |
| Delete instance | `subaccount_service_instance_manage` | `container_service_instance_manage` |
### Bindings API
| Operation | Required Scope (subaccount) | Required Scope (container) |
|-----------|----------------------------|---------------------------|
| List bindings | `subaccount_service_binding_read` | `container_service_binding_read` |
| Get binding | `subaccount_service_binding_read` | `container_service_binding_read` |
| Create binding | `subaccount_service_binding_manage` | `container_service_binding_manage` |
| Delete binding | `subaccount_service_binding_manage` | `container_service_binding_manage` |
### Plans & Offerings API
| Operation | Required Scope |
|-----------|----------------|
| List plans | `subaccount_service_plan_read` |
| Get plan | `subaccount_service_plan_read` |
| List offerings | `subaccount_service_offering_read` |
| Get offering | `subaccount_service_offering_read` |
---
## Token Scope Verification
**Check token scopes**:
```bash
# Decode JWT token (without verification)
echo "<access_token>" | cut -d'.' -f2 | base64 -d | jq '.scope'
```
**Expected format**:
```json
{
"scope": [
"<xsappname>.subaccount_service_instance_manage",
"<xsappname>.subaccount_service_instance_read",
...
]
}
```
---
## Best Practices
1. **Principle of Least Privilege**: Use audit plan for read-only needs
2. **Container Isolation**: Use container plan for application self-service
3. **Separate Credentials**: Different credentials for different environments
4. **Rotate Credentials**: Regular rotation of client secrets
5. **Audit Access**: Monitor who has admin access
6. **X.509 for Production**: Use certificate auth in production
---
## Documentation Links
- **Broker Plans**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-broker-plans-917a8a7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-broker-plans-917a8a7.md)
- **Roles**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-roles-d95fbe7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-roles-d95fbe7.md)
- **Role Assignment**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/assign-the-subaccount-service-administrator-collection-0735965.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/assign-the-subaccount-service-administrator-collection-0735965.md)

300
references/service-catalog-legacy.md Normal file
View File

@@ -0,0 +1,300 @@
# Service Catalog (svcat) and Broker Proxy Reference
Legacy Kubernetes integration using Service Catalog and Service Manager Broker Proxy.
**Note**: For new installations, prefer the SAP BTP Service Operator. See `kubernetes-operator.md`.
**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. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Installation](#installation)
- [Install Service Catalog](#install-service-catalog)
- [Configure Broker Proxy](#configure-broker-proxy)
4. [Usage](#usage)
- [List Services](#list-services)
- [Create Instance](#create-instance)
- [Create Binding](#create-binding)
5. [Migration to Service Operator](#migration-to-service-operator)
- [Migration Steps](#migration-steps)
- [Key Differences](#key-differences)
6. [Troubleshooting](#troubleshooting)
- [Common Issues](#common-issues)
7. [Deprecation Notice](#deprecation-notice)
---
## Overview
Before the SAP BTP Service Operator, Kubernetes clusters used:
1. **Service Catalog (svcat)** - Kubernetes SIG project for service management
2. **Service Manager Broker Proxy** - Connects Service Catalog to SAP Service Manager
This approach is now **deprecated** in favor of the SAP BTP Service Operator.
---
## Prerequisites
- Kubernetes cluster with kubeconfig
- kubectl v1.17.4+ compatible
- Helm v3.x
- SMCTL CLI installed and logged in
- SAP Service Manager subscription
---
## Cluster Configuration
### Step 1: Register the Cluster as a Platform
```bash
# Register Kubernetes cluster with Service Manager
smctl register-platform <platform-name> kubernetes
# Note: Platform name must be unique within the region
# Returns credentials (username/password) needed for broker proxy
```
**Save the returned credentials** - they are needed for the broker proxy installation.
---
### Step 2: Install Service Catalog
```bash
# Add Service Catalog Helm repository
helm repo add svc-cat [https://svc-catalog-charts.storage.googleapis.com](https://svc-catalog-charts.storage.googleapis.com)
# Create catalog namespace
kubectl create namespace catalog
# Install Service Catalog
helm install catalog svc-cat/catalog --namespace catalog
```
**Version Note**: svcat v0.3.0 is required for compatibility with Kubernetes v1.17.4+.
**Verify Installation**:
```bash
kubectl get pods -n catalog
```
---
### Step 3: Install Service Manager Broker Proxy
```bash
# Add Peripli Helm repository
helm repo add peripli [https://peripli.github.io](https://peripli.github.io)
# Create namespace
kubectl create namespace service-broker-proxy
# Install broker proxy
helm install service-broker-proxy peripli/service-broker-proxy \
--namespace service-broker-proxy \
--version 0.7.0 \
--set config.sm.url=[https://service-manager.cfapps.<region>.hana.ondemand.com](https://service-manager.cfapps.<region>.hana.ondemand.com) \
--set sm.user=<username-from-step-1> \
--set sm.password=<password-from-step-1>
```
**SM_URL Format**: `[https://service-manager.cfapps.<landscape](https://service-manager.cfapps.<landscape) domain>`
**Regional Examples**:
- EU10 (Frankfurt): `[https://service-manager.cfapps.eu10.hana.ondemand.com`](https://service-manager.cfapps.eu10.hana.ondemand.com`)
- US10 (US East): `[https://service-manager.cfapps.us10.hana.ondemand.com`](https://service-manager.cfapps.us10.hana.ondemand.com`)
---
## Service Catalog CLI (svcat)
### Installation
**Mac OS**:
```bash
# Download binary
curl -sLO [https://download.svcat.sh/cli/latest/darwin/amd64/svcat](https://download.svcat.sh/cli/latest/darwin/amd64/svcat)
# Make executable
chmod +x ./svcat
# Move to PATH
sudo mv ./svcat /usr/local/bin/
# Verify
svcat version --client
```
**Windows**:
```powershell
# Download executable
iwr [https://download.svcat.sh/cli/latest/windows/amd64/svcat.exe](https://download.svcat.sh/cli/latest/windows/amd64/svcat.exe) -o svcat.exe
# Create bin directory
mkdir ~\bin
# Move executable
Move-Item svcat.exe ~\bin\
# Add to PATH (PowerShell profile)
$env:PATH += ";$HOME\bin"
# Verify
svcat version --client
```
**Reference**: [https://svc-cat.io/docs/install/#installing-the-service-catalog-cli](https://svc-cat.io/docs/install/#installing-the-service-catalog-cli)
---
## svcat Commands
### Browse Marketplace
```bash
# List all available services
svcat marketplace
# Short form
svcat mp
```
---
### Provision Service Instance
```bash
# Create service instance
svcat provision <instance-name> --class <service-name> --plan <plan-name>
# Example: Create XSUAA instance
svcat provision my-xsuaa --class xsuaa --plan application
# With parameters
svcat provision my-hana --class hana --plan hdi-shared \
--param database_id=<hana-db-guid>
```
---
### List Instances
```bash
# List all provisioned instances
svcat get instances
```
---
### Deprovision Service Instance
```bash
# Delete service instance
svcat deprovision <instance-name>
```
---
### Create Binding
```bash
# Create binding for instance
svcat bind <instance-name>
# With specific binding name
svcat bind <instance-name> --name <binding-name>
```
---
### List Bindings
```bash
# List all bindings
svcat get bindings
```
---
### Delete Binding
```bash
# Remove binding
svcat unbind <instance-name> --name <binding-name>
```
---
### Get Credentials
```bash
# View binding credentials (stored in Kubernetes secret)
kubectl get secret <binding-name> -o yaml
```
---
## Migration to SAP BTP Service Operator
**Important**: Service Catalog is deprecated. Migrate to SAP BTP Service Operator.
See `kubernetes-operator.md` for:
- SAP BTP Service Operator setup
- Migration procedure from svcat
- ServiceInstance and ServiceBinding CRDs
### Quick Migration Overview
1. Install SAP BTP Service Operator (see `kubernetes-operator.md`)
2. Install migration CLI tool
3. Prepare platform: `smctl curl -X PATCH "/v1/platforms/<platformID>" -d '{"credentials":{"rotatable":true}}'`
4. Dry run: `btpmigrate --dry-run`
5. Execute: `btpmigrate`
**Warning**: Once migration starts, the platform becomes suspended. The process is reversible until actual resource migration begins.
---
## Troubleshooting
### Service Catalog Not Finding Services
**Check**:
1. Broker proxy running: `kubectl get pods -n service-broker-proxy`
2. Service Manager credentials valid
3. Platform registered: `smctl list-platforms`
### Provisioning Fails
**Check**:
1. Service entitled in subaccount
2. Correct plan name
3. Broker proxy logs: `kubectl logs -n service-broker-proxy deployment/service-broker-proxy`
### svcat Command Not Found
**Solution**: Ensure svcat is in PATH:
```bash
# Mac/Linux
export PATH=$PATH:/usr/local/bin
# Or reinstall
curl -sLO [https://download.svcat.sh/cli/latest/darwin/amd64/svcat](https://download.svcat.sh/cli/latest/darwin/amd64/svcat)
chmod +x svcat
sudo mv svcat /usr/local/bin/
```
---
## Documentation Links
- **Cluster Configuration**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/cluster-configuration-a55506d.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/cluster-configuration-a55506d.md)
- **Service Catalog Guide**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/working-with-service-catalog-86ab6f9.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/Consuming-SAP-BTP-Services-from-Various-Environments/working-with-service-catalog-86ab6f9.md)
- **Service Catalog Official**: [https://svc-cat.io/docs/](https://svc-cat.io/docs/)
- **Migration Guide**: [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)

740
references/smctl-commands.md Normal file
View File

@@ -0,0 +1,740 @@
# SMCTL Command Reference
Service Manager Control (SMCTL) is the CLI for SAP Service Manager.
**Installation**: [https://github.com/Peripli/service-manager-cli/releases/latest](https://github.com/Peripli/service-manager-cli/releases/latest)
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
---
## Table of Contents
1. [Global Flags](#global-flags)
2. [Authentication Commands](#authentication-commands)
- [smctl login](#smctl-login)
- [smctl logout](#smctl-logout)
3. [Service Instance Commands](#service-instance-commands)
- [smctl provision](#smctl-provision)
- [smctl deprovision](#smctl-deprovision)
- [smctl list-instances](#smctl-list-instances)
- [smctl get-instance](#smctl-get-instance)
- [smctl update-instance](#smctl-update-instance)
4. [Service Binding Commands](#service-binding-commands)
- [smctl bind](#smctl-bind)
- [smctl unbind](#smctl-unbind)
- [smctl list-bindings](#smctl-list-bindings)
- [smctl get-binding](#smctl-get-binding)
5. [Service Broker Commands](#service-broker-commands)
- [smctl register-broker](#smctl-register-broker)
- [smctl update-broker](#smctl-update-broker)
- [smctl list-brokers](#smctl-list-brokers)
- [smctl delete-broker](#smctl-delete-broker)
6. [Platform Commands](#platform-commands)
- [smctl register-platform](#smctl-register-platform)
- [smctl update-platform](#smctl-update-platform)
- [smctl list-platforms](#smctl-list-platforms)
- [smctl delete-platform](#smctl-delete-platform)
7. [Marketplace Commands](#marketplace-commands)
- [smctl marketplace](#smctl-marketplace)
8. [Operations Commands](#operations-commands)
- [smctl status](#smctl-status)
- [smctl list-operations](#smctl-list-operations)
9. [Common Examples](#common-examples)
10. [Tips and Best Practices](#tips-and-best-practices)
---
## Global Flags
Available on all commands:
| Flag | Description |
|------|-------------|
| `--config <path>` | Path to config.json (default: `$HOME/.sm/config.json`) |
| `-v, --verbose` | Enable verbose output |
| `-h, --help` | Display help |
---
## Authentication Commands
### smctl login
Authenticate to SAP Service Manager.
**Syntax**:
```bash
smctl login [flags]
```
**Aliases**: `login`, `l`
**Required Flags**:
| Flag | Description |
|------|-------------|
| `-a, --url <url>` | Base URL for SAP Service Manager |
| `--param subdomain=<value>` | Subaccount subdomain (required) |
**Optional Flags**:
| Flag | Description |
|------|-------------|
| `-u, --user <user>` | User ID |
| `-p, --password <pass>` | Password |
| `--auth-flow <flow>` | `password` (default) or `client-credentials` |
| `--client-id <id>` | Client ID for client-credentials flow |
| `--client-secret <secret>` | Client secret |
| `--cert <path>` | Path to certificate file (X.509) |
| `--key <path>` | Path to private key file (X.509) |
| `--skip-ssl-validation` | Skip SSL verification (not recommended) |
**Examples**:
```bash
# Interactive password login
smctl login -a [https://service-manager.cfapps.eu10.hana.ondemand.com](https://service-manager.cfapps.eu10.hana.ondemand.com) \
--param subdomain=my-subaccount
# Client credentials (default)
smctl login -a [https://service-manager.cfapps.eu10.hana.ondemand.com](https://service-manager.cfapps.eu10.hana.ondemand.com) \
--param subdomain=my-subaccount \
--auth-flow client-credentials \
--client-id abc123 \
--client-secret xyz789
# Client credentials (X.509)
smctl login -a [https://service-manager.cfapps.eu10.hana.ondemand.com](https://service-manager.cfapps.eu10.hana.ondemand.com) \
--param subdomain=my-subaccount \
--auth-flow client-credentials \
--client-id abc123 \
--cert /path/to/cert.pem \
--key /path/to/key.pem
```
**2FA Note**: If 2FA enabled, append passcode to password (e.g., `Password1234` + `5678` = `Password12345678`)
**Session**: Expires after 30 minutes of inactivity.
---
### smctl logout
End current session.
**Syntax**:
```bash
smctl logout
```
---
## Instance Commands
### smctl provision
Create a service instance.
**Syntax**:
```bash
smctl provision [name] [offering] [plan] [flags]
```
**Arguments**:
| Argument | Description |
|----------|-------------|
| `name` | Instance name |
| `offering` | Service offering name |
| `plan` | Service plan name |
**Flags**:
| Flag | Description |
|------|-------------|
| `-b, --broker-name <name>` | Broker name (if offering name conflicts) |
| `--mode <mode>` | `sync` or `async` (default: async) |
| `-c, --parameters <json>` | JSON configuration parameters |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# Basic provisioning (async)
smctl provision my-instance xsuaa application
# Sync mode
smctl provision my-instance xsuaa application --mode sync
# With parameters
smctl provision my-instance hana hdi-shared \
-c '{"database_id":"abc-123"}'
# JSON output
smctl provision my-instance xsuaa application -o json
```
---
### smctl deprovision
Delete a service instance.
**Syntax**:
```bash
smctl deprovision [name] [flags]
```
**Flags**:
| Flag | Description |
|------|-------------|
| `-f, --force` | Delete without confirmation |
| `-id <id>` | Instance ID (if name not unique) |
| `--mode <mode>` | `sync` or `async` (default: async) |
**Examples**:
```bash
# Interactive deletion
smctl deprovision my-instance
# Force delete (no confirmation)
smctl deprovision my-instance -f
# Sync mode
smctl deprovision my-instance --mode sync -f
```
---
### smctl list-instances
List all service instances.
**Syntax**:
```bash
smctl list-instances [flags]
```
**Aliases**: `list-instances`, `li`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Output columns**: ID, Name, Service Plan, Platform, Created, Updated, Ready, Usable, Labels
---
### smctl get-instance
Get details of a specific instance.
**Syntax**:
```bash
smctl get-instance [name] [flags]
```
**Aliases**: `get-instance`, `gi`
**Flags**:
| Flag | Description |
|------|-------------|
| `-id <id>` | Instance ID (if name not unique) |
| `--show-instance-params` | Show service instance configuration parameters |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# Basic retrieval
smctl get-instance sample-instance
# With configuration parameters
smctl get-instance sample-instance --show-instance-params
# JSON output
smctl get-instance sample-instance -o json
```
**Output**: ID, Name, Service Plan ID, Platform ID, Created, Updated, Ready, Usable, Labels, Last Operation
---
## Binding Commands
### smctl bind
Create a service binding.
**Syntax**:
```bash
smctl bind [instance-name] [binding-name] [flags]
```
**Flags**:
| Flag | Description |
|------|-------------|
| `--mode <mode>` | `sync` or `async` (default: async) |
| `-c, --parameters <json>` | JSON configuration |
| `-id <id>` | Instance ID (if name not unique) |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# Basic binding
smctl bind my-instance my-binding
# With X.509 credentials
smctl bind my-instance my-binding -c '{"credential-type":"x509"}'
# X.509 with custom validity
smctl bind my-instance my-binding -c '{
"credential-type": "x509",
"key-length": 4096,
"validity-type": "MONTHS",
"validity": 6
}'
# Sync mode
smctl bind my-instance my-binding --mode sync
```
**X.509 Parameters**:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `credential-type` | - | Set to `x509` for certificate auth |
| `key-length` | 2048 | Private key length in bytes |
| `validity-type` | DAYS | `DAYS`, `MONTHS`, or `YEARS` |
| `validity` | 7 | Number of validity units |
---
### smctl unbind
Delete a service binding.
**Syntax**:
```bash
smctl unbind [instance-name] [binding-name] [flags]
```
**Flags**:
| Flag | Description |
|------|-------------|
| `-f, --force` | Delete without confirmation |
| `--mode <mode>` | `sync` or `async` (default: async) |
| `-id <id>` | Binding ID (if name not unique) |
---
### smctl list-bindings
List all service bindings.
**Syntax**:
```bash
smctl list-bindings [flags]
```
**Aliases**: `list-bindings`, `lsb`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
---
### smctl get-binding
Get details of a specific binding (includes credentials).
**Syntax**:
```bash
smctl get-binding [name] [flags]
```
**Aliases**: `get-binding`, `gsb`
**Flags**:
| Flag | Description |
|------|-------------|
| `-id <id>` | Binding ID (if name not unique) |
| `--show-binding-params` | Show service binding configuration parameters |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# Basic retrieval
smctl get-binding sample-binding
# With binding parameters
smctl get-binding sample-binding --show-binding-params
# JSON output
smctl get-binding sample-binding -o json
```
**Output**: ID, Name, Instance Name, Credentials, Created, Updated, Ready, Labels, Last Operation
---
## Broker Commands
### smctl register-broker
Register a service broker.
**Syntax**:
```bash
smctl register-broker [name] [url] <description> [flags]
```
**Aliases**: `register-broker`, `rb`
**Required Flags**:
| Flag | Description |
|------|-------------|
| `-b, --basic <user:pass>` | Basic auth credentials |
**Optional Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl register-broker my-broker [https://broker.example.com](https://broker.example.com) "My broker" \
-b admin:password123
```
---
### smctl update-broker
Update a registered broker.
**Syntax**:
```bash
smctl update-broker [name] <json_broker> [flags]
```
**Aliases**: `update-broker`, `ub`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl update-broker broker '{"name": "new-name", "description": "new-description", "broker_url": "[http://broker.com",](http://broker.com",) "credentials": { "basic": { "username": "admin", "password": "admin" }}}'
```
---
### smctl list-brokers
List all registered brokers.
**Syntax**:
```bash
smctl list-brokers [flags]
```
**Aliases**: `list-brokers`, `lb`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Output columns**: ID, Name, URL, Description, Created, Updated
---
### smctl delete-broker
Delete one or more registered brokers.
**Syntax**:
```bash
smctl delete-broker [name] <name2> <name3> ... [flags]
```
**Aliases**: `delete-broker`, `db`
**Flags**:
| Flag | Description |
|------|-------------|
| `-f, --force` | Delete without confirmation |
**Example**:
```bash
smctl delete-broker sample-broker-1
# Output: Broker with name: sample-broker-1 successfully deleted
```
---
## Platform Commands
### smctl register-platform
Register a platform.
**Syntax**:
```bash
smctl register-platform [name] [type] <description> [flags]
```
**Aliases**: `register-platform`, `rp`
**Flags**:
| Flag | Description |
|------|-------------|
| `-i, --id <id>` | Custom platform ID (auto-generated if omitted) |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl register-platform my-k8s-cluster kubernetes "Production K8s cluster"
```
---
### smctl update-platform
Update a registered platform.
**Syntax**:
```bash
smctl update-platform [name] <json_platform> [flags]
```
**Aliases**: `update-platform`, `up`
**Flags**:
| Flag | Description |
|------|-------------|
| `--regenerate-credentials` | Generate new credentials (old credentials become invalid) |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl update-platform platform '{"name": "new-name", "description": "new-description", "type": "new-type"}'
```
**Note**: When using `--regenerate-credentials`, old credentials can no longer be used.
---
### smctl list-platforms
List all registered platforms.
**Syntax**:
```bash
smctl list-platforms [flags]
```
**Aliases**: `list-platforms`, `lp`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Output columns**: ID, Name, Type, Description, Created, Updated
---
### smctl delete-platform
Delete one or more platforms.
**Syntax**:
```bash
smctl delete-platform <name1> <name2> ... <nameN> [flags]
```
**Aliases**: `delete-platform`, `dp`
**Flags**:
| Flag | Description |
|------|-------------|
| `-f, --force` | Delete without confirmation |
| `--cascade-delete` | Delete asynchronously with cascade (returns operation URL) |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# Standard deletion
smctl delete-platform sample-platform
# Output: Platform with name: sample-platform successfully deleted
# Cascade delete (async)
smctl delete-platform sample-platform --cascade-delete
# Returns: smctl status /v1/platforms/{id}/operations/{operation-id}
```
**Note**: Cascade delete schedules an async operation; use `smctl status` to monitor.
---
## Marketplace Commands
### smctl marketplace
List available service offerings and plans.
**Syntax**:
```bash
smctl marketplace [flags]
```
**Aliases**: `marketplace`, `m`
**Flags**:
| Flag | Description |
|------|-------------|
| `-s, --service <name>` | Show plans for specific service |
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Examples**:
```bash
# List all offerings
smctl marketplace
# List plans for specific service
smctl marketplace -s xsuaa
```
---
### smctl list-offerings
List all service offerings associated with the Service Manager.
**Syntax**:
```bash
smctl list-offerings [flags]
```
**Aliases**: `list-offerings`, `lo`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl list-offerings
smctl lo -o json
```
**Output columns**: ID, Name, Description, Broker ID, Ready, Labels
---
### smctl list-plans
List all service plans associated with the Service Manager.
**Syntax**:
```bash
smctl list-plans [flags]
```
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Example**:
```bash
smctl list-plans
smctl list-plans -o json
```
**Output columns**: ID, Name, Description, Offering ID, Ready, Labels
---
## Status Commands
### smctl status
Check async operation status.
**Syntax**:
```bash
smctl status <operation-url>
```
**Example**:
```bash
# After async provision
smctl status /v1/service_instances/abc-123/operations/op-456
```
---
## Other Commands
### smctl help
Display help for any command.
**Syntax**:
```bash
smctl help [command]
smctl [command] --help
```
### smctl info
Display information about the connected SAP Service Manager instance.
**Syntax**:
```bash
smctl info [flags]
```
**Aliases**: `info`, `i`
**Flags**:
| Flag | Description |
|------|-------------|
| `-o, --output <format>` | `json`, `yaml`, or `text` |
**Output**: Service Management URL and authenticated user account.
---
### smctl version
Display SMCTL version information.
**Syntax**:
```bash
smctl version [flags]
```
**Aliases**: `version`, `v`
**Example**:
```bash
smctl version
# Output: Service Management Client 0.0.1
```
---
## Documentation Links
- **Installation**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/installing-the-service-manager-control-smctl-command-line-tool-93532bd.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/installing-the-service-manager-control-smctl-command-line-tool-93532bd.md)
- **Login**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/login-a8ed7cf.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/login-a8ed7cf.md)
- **Provision**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/provision-b327b66.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/provision-b327b66.md)
- **Bind**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/bind-f53ff26.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/bind-f53ff26.md)
- **Get Instance**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-instance-24fb85c.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-instance-24fb85c.md)
- **Get Binding**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-binding-8495036.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/get-binding-8495036.md)
- **List Offerings**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/list-offerings-8a0659f.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/list-offerings-8a0659f.md)
- **List Plans**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/list-plans-b0e4863.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/list-plans-b0e4863.md)
- **GitHub Releases**: [https://github.com/Peripli/service-manager-cli/releases](https://github.com/Peripli/service-manager-cli/releases)