Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
salaboy authored Sep 21, 2023
1 parent 9d73bb1 commit de910f4
Showing 1 changed file with 20 additions and 20 deletions.
40 changes: 20 additions & 20 deletions chapter-6/README.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
# Chapter 6 :: Let's build a Platform on top of Kubernetes

---
_🌍 Available in_: [English](README.md)
_🌍 Available in_: [English](README.md) | [中文 (Chinese)](README-zh.md)

> **Note:** Brought to you by the fantastic cloud-native community's [ 🌟 contributors](https://github.com/salaboy/platforms-on-k8s/graphs/contributors)!
---


On this step-by-step tutorial we will create the APIs of our platform by reusing the power of the Kubernetes APIs. The first use case where the platform can assist the development teams is by creating new development environments providing a self-service approach.
In this step-by-step tutorial, we will create our platform's APIs by reusing the Kubernetes APIs' power. The first use case where the platform can assist the development teams is by creating new development environments and providing a self-service approach.

To build this example we will be using Crossplane and `vcluster`, two Open Source projects hosted in the Cloud-Native Computing Foundation.
To build this example, we will use Crossplane and `vcluster`, two Open Source projects hosted in the Cloud-Native Computing Foundation.

## Installation

To install Crossplane you need to have a Kubernetes Cluster, you can create one using KinD as we did for you [Chapter 2](../chapter-2/README.md#creating-a-local-cluster-with-kubernetes-kind).
To install Crossplane, you need to have a Kubernetes Cluster; you can create one using KinD as we did for you [Chapter 2](../chapter-2/README.md#creating-a-local-cluster-with-kubernetes-kind).

Then you can install Crossplane and the Crossplane Helm Provider in your cluster as we did in [Chapter 5](https://github.com/salaboy/platforms-on-k8s/tree/main/chapter-5#installing-crossplane)

We will be using [`vcluster`](https://www.vcluster.com/) in this tutorial, but there is no need to install anything in our cluster for vcluster to work. We just need the `vcluster` CLI to connect to our `vcluster`s you can install it by following the instructions on the official site: [https://www.vcluster.com/docs/getting-started/setup](https://www.vcluster.com/docs/getting-started/setup)
We will use [`vcluster`](https://www.vcluster.com/) in this tutorial, but there is no need to install anything in our cluster for vcluster to work. We need the `vcluster` CLI to connect to our `vcluster`s you can install it by following the instructions on the official site: [https://www.vcluster.com/docs/getting-started/setup](https://www.vcluster.com/docs/getting-started/setup)


## Defining our Environment API

An environment represent a Kubernetes cluster where the Conference Application will be installed for development purposes. The idea is to provide teams with self-service environments for them to do their work.
An environment represents a Kubernetes cluster where the Conference Application will be installed for development. The idea is to provide teams with self-service environments for them to do their work.

For this tutorial we will define a Environment API and a Crossplane Composition that uses the Helm Provider to create a new instance of `vcluster`.
For this tutorial, we will define an Environment API and a Crossplane Composition that uses the Helm Provider to create a new instance of `vcluster`.

Check the Crossplane Composite Resource Definition (XRD) for our [Environments here](resources/env-resource-definition.yaml) and the Crossplane [Composition here](resources/composition-devenv.yaml). This resource configures the provisioning of a new `vcluster` using the Crossplane Helm Provider, [check this configuration here](https://github.com/salaboy/platforms-on-k8s/blob/main/chapter-6/resources/composition-devenv.yaml#L24). When a new `vcluster` is created then the composition install our Conference Application into it, once again using the Crossplane Helm Provider, but this time configured [pointing to the just created `vcluster` APIs](https://github.com/salaboy/platforms-on-k8s/blob/main/chapter-6/resources/composition-devenv.yaml#L87), you can [check this here](https://github.com/salaboy/platforms-on-k8s/blob/main/chapter-6/resources/composition-devenv.yaml#L117).

Expand All @@ -46,7 +46,7 @@ With the Environment resource and the Crossplane Composition using `vcluster` ou

## Requesting a new Environment

To request a new Environment teams can create new environment resources like this one:
To request a new Environment, teams can create new environment resources like this one:

```yaml
apiVersion: salaboy.com/v1alpha1
Expand Down Expand Up @@ -106,7 +106,7 @@ Then we can connect to the provisioned environment by running (use the CONNECT-T
vcluster connect team-a-dev-env-jp7j4 --server https://localhost:8443 -- zsh
```

Once you are connected to the `vcluster` you are in a different Kubernetes Cluster, so if you list all the available namespaces you should see:
Once you are connected to the `vcluster` you are in a different Kubernetes Cluster, so if you list all the available namespaces, you should see:

```shell
kubectl get ns
Expand Down Expand Up @@ -137,16 +137,16 @@ kubectl port-forward svc/frontend 8080:80
Now your application is available at [http://localhost:8080](http://localhost:8080)


You can exit the vcluster context by typing `exit` in the terminal.
You can exit the `vcluster` context by typing `exit` in the terminal.


## Simplifying our platform surface

We can go one step further to simplify the interaction with the platform APIs, avoiding teams to connect to the Platform Cluster and remove the need for having access to the Kubernetes APIs.
We can go one step further to simplify the interaction with the platform APIs, preventing teams from connecting to the Platform Cluster and removing the need for having access to the Kubernetes APIs.

In this short section we deploy an Admin User Interface that allow teams to request new environments using a website, or a set of simplified REST APIs.
In this short section, we deploy an Admin User Interface that allows teams to request new environments using a website, or a set of simplified REST APIs.

Before installing the Admin User Interface you need to make sure that you are not inside a `vcluster` session. (You can exit the vcluster context by typing `exit` in the terminal). Check that you have the `crossplane-system` namespaces in the current cluster were you are connected.
Before installing the Admin User Interface, you need to make sure that you are not inside a `vcluster` session. (You can exit the `vcluster` context by typing `exit` in the terminal). Check that you have the `crossplane-system` namespaces in the current cluster where you are connected.

You can install this Admin User Interface using Helm:

Expand All @@ -160,13 +160,13 @@ Once installed you can port-forward to the Admin UI by running:
kubectl port-forward svc/admin 8081:80
```

Now you can create and check your environments using a simple interface. If you wait for the environment to be ready you will get the `vcluster` command to use to connect to the environment.
Now you can create and check your environments using a simple interface. If you wait for the environment to be ready, you will get the `vcluster` command to use to connect to the environment.

![imgs/admin-ui.png](imgs/admin-ui.png)

By using this simple interface, development teams will not need to access the Kubernetes APIs from the cluster which has all the platform tools (Crossplane and Argo CD for example) directly.

Besides the User interface, the Platform Admin application offers you a simplified set of REST endpoints where you have full flexibility to define how the resources looks like instead of following the Kubernetes Resource Model. For example, instead of having a Kubernetes Resource with all the metadata needed by the Kubernetes API, we can use the following JSON payload to create a new Environment:
Besides the User interface, the Platform Admin application offers you a simplified set of REST endpoints where you have full flexibility to define how the resources look like instead of following the Kubernetes Resource Model. For example, instead of having a Kubernetes Resource with all the metadata needed by the Kubernetes API, we can use the following JSON payload to create a new Environment:

```json
{
Expand Down Expand Up @@ -198,7 +198,7 @@ Or delete one environment running:
curl -X DELETE http://localhost:8081/api/environments/team-curl-dev-env
```

This application serves as a facade between Kubernetes and the outside world. Depending on your organization needs, you might want to have this abstractions (APIs) early on, so the platform team can pivot on their tooling and workflow decisions under the covers.
This application serves as a facade between Kubernetes and the outside world. Depending on your organization's needs, you might want to have these abstractions (APIs) early on, so the platform team can pivot on their tooling and workflow decisions under the covers.


## Clean up
Expand All @@ -212,7 +212,7 @@ kind delete clusters dev

## Next Steps

Can you extend the Admin User Interface to create Databases and Message Brokers like we did in Chapter 5? What would it take? Understanding where the changes needs to be made will give you hands-on experience on developing components that interact with the Kubernetes APIs and provide simplified interfaces for consumers.
Can you extend the Admin User Interface to create Databases and Message Brokers like we did in Chapter 5? What would it take? Understanding where the changes need to be made will give you hands-on experience in developing components that interact with the Kubernetes APIs and provide simplified interfaces for consumers.

Can you create your own compositions to use Real Clusters instead of `vcluster`? For which kind of scenario would you use a real Cluster and when a `vcluster`?

Expand All @@ -222,8 +222,8 @@ What extra steps would you need to do to run this in a real Kubernetes Cluster i

## Sum up and Contribute

On this tutorial we have built a new Platform API reusing the Kubernetes Resource model to provision on demand development environments. On top of that with the Platform Admin application we have created a simplified layer to expose the same capabilities without pushing teams to learn about how Kubernetes work or the underlaying details, projects and technologies that we have used to build our Platform.
In this tutorial, we have built a new Platform API reusing the Kubernetes Resource model to provision on-demand development environments. On top of that with the Platform Admin application we have created a simplified layer to expose the same capabilities without pushing teams to learn about how Kubernetes works or the underlying details, projects, and technologies that we have used to build our Platform.

By relying on contracts (for this example the Environment resource definition), the platform team have the flexibility to change the mechanisms used to provision environments depending on their requirements and available tools.
By relying on contracts (for this example the Environment resource definition), the platform team has the flexibility to change the mechanisms used to provision environments depending on their requirements and available tools.

Do you want to improve this tutorial? Create an issue, drop me a message on [Twitter](https://twitter.com/salaboy) or send a Pull Request.
Do you want to improve this tutorial? Create an issue, drop me a message on [Twitter](https://twitter.com/salaboy), or send a Pull Request.

0 comments on commit de910f4

Please sign in to comment.