We will be creating a state directory and informing pulumi we want to use that local directory to manage the state, no need to use a cloud backend managed by pulumi or other providers (for the sake of testing).
This means that, to execute, you just need to type `make run` and to destroy, you need to type `make destroy`.
## Creating a Network
We address here how to create a [network](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/network).
### Pulumi File
You can find the original file [here](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/network/Pulumi.yaml).
```yml
name: pulumi-provider-grid
runtime: yaml
plugins:
providers:
- name: grid
path: ../..
resources:
provider:
type: pulumi:providers:grid
properties:
mnemonic:
scheduler:
type: grid:internal:Scheduler
options:
provider: ${provider}
properties:
farm_ids: [1]
network:
type: grid:internal:Network
options:
provider: ${provider}
dependsOn:
- ${scheduler}
properties:
name: testing
description: test network
nodes:
- ${scheduler.nodes[0]}
ip_range: 10.1.0.0/16
outputs:
node_deployment_id: ${network.node_deployment_id}
nodes_ip_range: ${network.nodes_ip_range}
```
We will now go through this file section by section to properly understand what is happening.
```yml
name: pulumi-provider-grid
runtime: yaml
```
- name is for the project name (can be anything)
- runtime: the runtime we are using can be code in yaml, python, go, etc.
```yml
plugins:
providers:
- name: grid
path: ../..
```
Here, we define the plugins we are using within our project and their locations. Note that we use `../..` due to the repository hierarchy.
```yml
resources:
provider:
type: pulumi:providers:grid
properties:
mnemonic:
```
We then start by initializing the resources. The provider which we loaded in the plugins section is also a resource that has properties (the main one now is just the mnemonic of TCHhain).
```yaml
scheduler:
type: grid:internal:Scheduler
options:
provider: ${provider}
properties:
farm_ids: [1]
```
Then, we create a scheduler `grid:internal:Scheduler`, that does the planning for us. Instead of being too specific about node IDs, we just give it some generic information. For example, "I want to work against these data centers (farms)". As long as the necessary criteria are provided, the scheduler can be more specific in the planning and select the appropriate resources available on the TFGrid.
```yaml
network:
type: grid:internal:Network
options:
provider: ${provider}
dependsOn:
- ${scheduler}
properties:
name: testing
description: test network
nodes:
- ${scheduler.nodes[0]}
ip_range: 10.1.0.0/16
```
Now, that we created the scheduler, we can go ahead and create the network resource `grid:internal:Network`. Please note that the network depends on the scheduler's existence. If we remove it, the scheduler and the network will be created in parallel, that's why we have the `dependsOn` section. We then proceed to specify the network resource properties, e.g. the name, the description, which nodes to deploy our network on, the IP range of the network. In our case, we only choose one node.
To access information related to our deployment, we set the section **outputs**. This will display results that we can use, or reuse, while we develop our infrastructure further.
```yaml
outputs:
node_deployment_id: ${network.node_deployment_id}
nodes_ip_range: ${network.nodes_ip_range}
```
## Creating a Virtual Machine
Now, we will check an [example](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/virtual_machine) on how to create a virtual machine.
Just like we've seen above, we will have two files `Makefile` and `Pulumi.yaml` where we describe the infrastructure.
We have a scheduler, and a network just like before. But now, we also have a deployment `grid:internal:Deployment` object that can have one or more disks and virtual machines.
The deployment can be linked to a network using `network_name` and can have virtual machines in the `vms` section, and disks in the `disks` section. The disk can be linked and mounted in the VM if `disk_name` is used in the `mounts` section of the VM.
We also specify a couple of essential properties, like how many virtual cores, how much memory, what FList to use, and the environment variables in the `env_vars` section.
That's it! You can now execute `make run` to bring the infrastructure up.
## Kubernetes
We now see how to deploy a [Kubernetes cluster using Pulumi](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/kubernetes/Pulumi.yaml).
Now, we define the Kubernetes resource `grid:internal:Kubernetes` that has master and workers blocks. You define almost everything like a normal VM except for the FLiist. Also note that the token is the `cluster token`. This will ensure that the workers and the master communicate properly.
## Creating a Domain
The ThreeFold Pulumi repository also covers examples on [how to work with TFGrid gateways](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/gateway_name/Pulumi.yaml).
The basic idea is that you have a virtual machine workload on a specific IP, e.g. public IPv4, IPv6, or Planetary Network, and you want to access it using domains.
There are two versions to achieve this, a simple and a fully controlled version.
- Simple domain version:
- subdomain.gent01.dev.grid.tf
- This is a generous service from ThreeFold to reserve a subdomain on a set of defined gateway domains like **gent01.dev.grid.tf**.
- Fully controlled domain version:
- e.g. `mydomain.com` where you manage the domain with the name provider.
### Example of a Simple Domain Prefix
We present here the file for a simple domain prefix.
In this example, we create a gateway name resource `grid:internal:GatewayName` for the name `pulumi.gent01.dev.grid.tf`.
Some things to note:
- **pulumi** is the prefix we want to reserve.
- It's assuming that the gateway domain we received by scheduler was the one managed by freefarm `gent01.dev.grid.tf`.
- **backends:** defines a list of IPs to load balance against when a request for `pulumi.gent01.dev.grid.tf` is received on the gateway.
### Example of a Fully Controlled Domain
Here's an [example](https://github.com/threefoldtech/pulumi-provider-grid/blob/development/examples/gateway_fqdn/Pulumi.yaml) of a more complicated, but fully controlled domain.
Here, we informed the gateway that any request coming for the domain `mydomain.com` needs to be balanced through the backends.
> Note: You need to create an A record for your domain (here `mydomain.com`) pointing to the gateway IP.
## Conclusion
We covered in this guide some basic details concerning the use of the ThreeFold Pulumi plugin.
If you have any questions, you can ask the ThreeFold community for help on the [ThreeFold Forum](http://forum.threefold.io/) or on the [ThreeFold Grid Tester Community](https://t.me/threefoldtesting) on Telegram.
