Tutorials
The tutorials on this page are the ideal place to get started on your service owner journey. They are meant to be run in order. The headlines give you orientation where you are in the process of getting UniPipe service broker up and running.
Have fun!
You'll need unipipe cli installed to follow the instructions on this page. 🕹️ How to install Unipipe CLI
Start by deploying UniPipe Service Broker as described in the How To Guides section.
After you have deployed UniPipe Service Broker, it's time to define a catalog.yml that UniPipe can advertise to Platforms.
We are going to use an example file provided by unipipe generate to generate a catalog with an example service offering.
Open a terminal and navigate into the instance repository. Use unipipe cli to generate an example catalog:
# UniPipe Service Broker expects catalog.yml in root of the instance repository
unipipe generate catalog --destination .Commit the catalog file and push your changes to the git repository.
The service broker fetches the catalog.yml and makes it available under https://<service-broker-url>/v2/catalog. To test this, simply open https://<service-broker-url>/v2/catalog with your browser and enter the basic auth credentials that are configured for your service broker.
Well done! With this setup you can advertise your service to any platform that speaks Open Service Broker API.
Register your service broker with a platform of your choice to explore your catalog on the platform.
The following page can be used to customize your catalog template for meshStack Platform. It is especially useful for customizing your widgets. https://docs.meshcloud.io/docs/meshstack.meshmarketplace.profile.html#things-to-keep-in-mind
Once you order your first instance, an instance.yml file will appear in the instance git repository. This is the file that your CI/CD pipeline will get all information it needs to manage the service instance.
In the next tutorial, you will learn how
unipipe transformallows you to process instance.yml files.
After you have created your first catalog and ordered a first instance, it's time to figure out how the CI/CD pipeline will work with instance.yml files.
We are going to use an example file provided by unipipe generate to generate a registry of handlers that we then use in unipipe transform on our example service offering. The advantage here is, that we can later use the same commands in our CI/CD pipeline to manage new instances without parsing YAML.
A handler is a typescript function that describes an output path and format for a service instance. Because catalog.yml holds a list of services and not every service might need the same transformation, we need to specify which handler is responsible for which service definition id.
Let's find out what service definition id we have in our catalog. If you have yq installed you can run cat catalog.yml | yq e '.services[].id' - to get a list of all service definition ids in your catalog.yml. Alternatively, do cat catalog.yml and check the id fields in the services list.
# Example output. Your result will differ, because `unipipe generate` uses randomly generated UUIDs for every generated catalog.
$ cat catalog.yml | yq e '.services[].id' -
"07555200-7f39-4125-81d3-7dd17a4bc38e"
"fa262d12-8b6b-4a45-b07a-27410cd87f9b"
"e0d19ebe-0fad-423b-a7ae-46f54b56ae84"Note down one of these ids for the following steps.
Use unipipe cli to generate a handler for this id.
$ unipipe generate transform-handler --handler handler_b --destination .
# Put in the id for your service definition id
? Write the Service Id that will be controlled by the handler. Press enter to continue. (Default: Auto-generated UUID) › 07555200-7f39-4125-81d3-7dd17a4bc38eThe generated handler produces a file under customers/$customer_id/$project_id/params.json that has the same context as the instance.yml file, but in JSON format.
Try to apply the handler by running
unipipe transform --registry-of-handlers handlers.js .If any instances are found that match the service definition id, the above command will create new files according to what's defined in handlers.js.
Good job! You are now ready to jump into developing your first UniPipe Service Broker pipeline.
Execution scripts are optional steps to perform your pipeline logic. The CI/CD pipelines(workflows) can also adapt the same logic as well. When the handler.js file creates the new serviceInstance folders/templates, you can use the execution-script to automate your resource creation or deletion. You can use unipipe generate execution-script command to create Terraform execution script as an example. This script also has logic that defines whether these serviceInstances will be created or deleted for each instance.
unipipe generate execution-script --destination .
We are going to use example files provided by unipipe generate to generate a GitHub actions pipeline that acts on commits by UniPipe.
Define a pipeline that acts on any commit
# GitHub expects workflow definitions in .github/workflows/
unipipe generate github-workflow --destination .github/workflows/Commit your Github workflow into your repository as .github/workflows/github-workflow.yml. Once the CI/CD pipeline is set, the workflow will look like below.
You can use the following mermaid.js code to create the same diagram
flowchart LR
MarketplaceService--New Instance Request-->OSBContainer
OSBContainer--Commit the request into the GIT repository-->CodeRepo
CodeRepo--Triggers CI/CD pipeline-->CodePipeline
subgraph PipelineSteps
direction LR
DownloadUnipipeCLI
DownloadTerraform
ExecuteUnipipeTransform
ExecuteShellScript
ExecuteUnipipeUpdate
end
CodePipeline-->PipelineSteps
PipelineSteps--Commit the latest changes with skip-ci method-->CodeRepo
Unipipe Service Broker can be used to expose your metrics. When Unipipe gets a new service instance request, it creates a new service instance folder under the instances folder and this folder is also the place to store your metric files if you want to expose them. Our Reference section has a lot of information about the implementation if you want to learn more about it.
Your journey is just beginning.
You can continue by 🕵️ Learning by examples