From c494b7ee198071a3ae93d85d1dade07404861f85 Mon Sep 17 00:00:00 2001 From: rebecca bausinger Date: Thu, 7 Aug 2025 14:57:13 +0200 Subject: [PATCH 1/2] implement-osb-guide --- docs/new-concept-osb-services.md | 23 ++--- docs/new-guide-how-to-implement-osb.md | 100 +++++++++++++++++++++ docs/new-guide-how-to-manage-osb.md | 119 +++++++++++++++++++++++++ 3 files changed, 227 insertions(+), 15 deletions(-) create mode 100644 docs/new-guide-how-to-implement-osb.md create mode 100644 docs/new-guide-how-to-manage-osb.md diff --git a/docs/new-concept-osb-services.md b/docs/new-concept-osb-services.md index 3b609be3a..6e1957848 100644 --- a/docs/new-concept-osb-services.md +++ b/docs/new-concept-osb-services.md @@ -67,21 +67,14 @@ If the above options do not work for your use case, you can also consider extrac <<<<<<< HEAD using the [meshObject API](pathname:///api/). - -======= ->>>>>>> c3370b4b (corrected-links) +### Guides + +- [How to Manage OSB Services](new-guide-how-to-manage-osb.md) +- [How to Implement an OSB Service Broker](new-guide-how-to-implement-osb.md) diff --git a/docs/new-guide-how-to-implement-osb.md b/docs/new-guide-how-to-implement-osb.md new file mode 100644 index 000000000..bf643a55b --- /dev/null +++ b/docs/new-guide-how-to-implement-osb.md @@ -0,0 +1,100 @@ +--- +id: meshstack.meshmarketplace.broker-tutorial +title: Tutorial: Implement a Broker +--- + +:::note What is this guide about? +This tutorial walks you through setting up a service broker that deploys services using CI/CD tools you already know. You'll learn about the Open Service Broker API, available libraries, and practical recommendations for implementation and testing. +::: + +## Prerequisites + +- Familiarity with cloud-native platforms and basic service provisioning concepts. +- Access to a CI/CD pipeline and a supported programming language (Java, Go, .NET, or Python). +- Understanding of your organization's requirements for service lifecycle management. + +## Step by Step Guide + +### 1. Understand the Open Service Broker API + +The [Open Service Broker API](https://www.openservicebrokerapi.org/) enables software vendors and developers to provide backing services to workloads running on cloud-native platforms. It defines a set of RESTful endpoints for provisioning, binding, and managing service offerings. + +- One broker can host multiple services. +- The API supports synchronous and asynchronous provisioning. +- Service brokers can add features like billing and backup/restore. + +### 2. Choose an Implementation Approach + +You can start with an existing project or library, or build your own broker from scratch. + +#### Quickstarts + +- **[Unipipe Service Broker](https://github.com/meshcloud/unipipe-service-broker):** + Example implementation that connects to a Git repository for catalog and instance management. Integrates with CI/CD pipelines. +- **[Spring Boot & Groovy OSB API](https://github.com/openservicebrokerapi/servicebroker):** + For Java/Spring developers. +- **[osb-service-broker-example](https://github.com/evoila/osb-example):** + Cloud Foundry-focused, requires custom logic for your service. +- **[osb-starter-pack](https://github.com/pmorie/osb-starter-pack):** + Go-based starter for rapid prototyping. + +#### Libraries + +- **Java:** + [Spring Cloud Open Service Broker](https://spring.io/projects/spring-cloud-open-service-broker) + [spring-cloud-app-broker](https://github.com/spring-cloud/spring-cloud-app-broker) +- **Go:** + [brokerapi](https://github.com/pivotal-cf/brokerapi) + [osb-broker-lib](https://github.com/pmorie/osb-broker-lib) + [Cloud service broker](https://github.com/pivotal/cloud-service-broker/) +- **.NET:** + [Open Service Broker API for .NET](https://github.com/AXOOM/OpenServiceBroker) +- **Python:** + [openbrokerapi](https://pypi.org/project/openbrokerapi/) + +### 3. Implement the Required Endpoints + +Each service broker must implement the OSBAPI endpoints: + +- **Catalog:** Returns the list of services and plans. +- **Provision:** Creates a new service instance. +- **Bind/Unbind:** Connects/disconnects applications to service instances. +- **Deprovision:** Deletes a service instance. + +Follow the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md) closely for request/response formats and error handling. + +### 4. Test Your Service Broker + +- Use the [API Swagger documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/openservicebrokerapi/servicebroker/v2.16/openapi.yaml#/) to understand and test endpoints. +- Try the [eden CLI](https://starkandwayne.com/blog/welcome-to-eden-a-cli-for-every-open-service-broker-api/) for local development and testing. +- Consider the [osb-checker tool](https://github.com/openservicebrokerapi/osb-checker) for compliance checks. + +### 5. Integrate with meshStack and CI/CD + +- If using Unipipe, connect your broker to a Git repository and configure your CI/CD pipeline to manage service instances. +- For other implementations, ensure your broker is reachable by meshStack and supports the required endpoints. + +### 6. Maintain and Evolve Your Broker + +- Use consistent IDs for services and plans. +- Implement proper error handling and support both synchronous and asynchronous operations. +- Plan for deprecation and removal of services or plans. +- Support multiple bindings per instance and create separate credentials for each binding. +- Provide admin endpoints for handling error states and orphaned resources. + +:::tip +Check out the [OSB API Compliant Service Brokers](https://www.openservicebrokerapi.org/compliant-service-brokers) catalog for inspiration and reference implementations. +::: + +## Related Resources + +### Concepts + +- [OSB Services](new-concept-osb-services.md) +- [Marketplace](new-concept-marketplace.md) + +### Guides + +- [How to Manage OSB Services](new-guide-how-to-manage-osb.md) +- [How to Manage a Project](new-guide-how-to-manage-a-project.md) +- [How to Manage a Workspace](new-guide-how-to-manage-a-workspace.md) \ No newline at end of file diff --git a/docs/new-guide-how-to-manage-osb.md b/docs/new-guide-how-to-manage-osb.md new file mode 100644 index 000000000..ed6084486 --- /dev/null +++ b/docs/new-guide-how-to-manage-osb.md @@ -0,0 +1,119 @@ +--- +id: new-guide-how-to-manage-osb +title: How to Manage OSB Services +--- + +:::note What is this guide about? +This guide shows you how to manage OSB (Open Service Broker) services in meshStack. You'll learn how to discover, provision, update, and maintain OSB services for your projects and workspaces. +::: + +:::warning +Please make sure OSBs are enabled for your meshStack. If you are not sure reach out to support@meshcloud.io +::: + +## Discover Available OSB Services + +### Prerequisites + +- You have access to meshPanel as a workspace or project manager. +- Your platform team has enabled OSB services in your meshStack environment. + +### Step by Step Guide + +1. Go to the **Marketplace** section in meshPanel. +2. Browse the list of available OSB services. +3. Use filters or search to find the service you need. + +## Provision a New OSB Service + +### Prerequisites + +- You have identified the OSB service you want to provision. +- You have the necessary permissions to provision services in your workspace or project. + +### Step by Step Guide + +1. Select the desired OSB service from the Marketplace. +2. Click **Provision** or **Create Instance**. +3. Fill out the required configuration fields (such as service plan, parameters, and target project or workspace). +4. Submit the form to start provisioning. +5. meshStack will handle the request and show you the status. + +## View and Manage Existing OSB Service Instances + +### Prerequisites + +- You have provisioned OSB services in your project or workspace. + +### Step by Step Guide + +1. Navigate to your project or workspace in meshPanel. +2. Open the **Service Instances** tab. +3. Review all provisioned OSB services. +4. Click on a service instance to view details, usage, and status. + +## Update an OSB Service Instance + +### Prerequisites + +- You have an existing OSB service instance that supports updates. +- You have permissions to modify service instances. + +### Step by Step Guide + +1. Select the service instance you want to update. +2. Choose **Edit** or **Update**. +3. Change the configuration as needed. +4. Save your changes. meshStack will apply the update and show the new status. + +## Delete an OSB Service Instance + +### Prerequisites + +- You have an OSB service instance you want to remove. +- You have permissions to delete service instances. + +### Step by Step Guide + +1. Select the service instance you want to delete. +2. Choose **Delete**. +3. Confirm the deletion. +4. meshStack will deprovision the service and update the status. + +## Monitor Service Health and Usage + +### Prerequisites + +- You have provisioned OSB services in your workspace or project. + +### Step by Step Guide + +1. Use the monitoring and logging features in meshPanel to track the health and consumption of your OSB services. +2. If you encounter issues, check the logs or contact your platform team for support. + +## Approve a Service Broker + +When a user publishes a service broker, an admin needs to approve it before its services become available in the marketplace catalog. + +### Prerequisites + +- You have admin permissions in meshPanel. +- A user has published a new service broker that requires approval. + +### Step by Step Guide + +1. Open meshPanel and navigate to the **Marketplace** > **Service Broker** section. +2. Locate the service broker awaiting approval. +3. Click the check button next to the broker to approve it. +4. After approval, the broker’s services will be available to all users in the marketplace. + +## Related Resources + +### Concepts + +- [Marketplace](new-concept-marketplace.md) +- [OSB Services](new-concept-osb-services.md) + +### Guides + +- [How to Implement an OSB Service Broker](new-guide-how-to-implement-osb.md) From 219e2e9146dedeabbeca9d618b86fb043d2eb80d Mon Sep 17 00:00:00 2001 From: rebecca bausinger Date: Thu, 7 Aug 2025 17:49:37 +0200 Subject: [PATCH 2/2] wrap --- docs/new-guide-how-to-implement-osb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/new-guide-how-to-implement-osb.md b/docs/new-guide-how-to-implement-osb.md index bf643a55b..5e0eb68ef 100644 --- a/docs/new-guide-how-to-implement-osb.md +++ b/docs/new-guide-how-to-implement-osb.md @@ -1,6 +1,6 @@ --- id: meshstack.meshmarketplace.broker-tutorial -title: Tutorial: Implement a Broker +title: "Tutorial: Implement a Broker" --- :::note What is this guide about?