Skip to content

Commit

Permalink
docs: prepare docs for next version (0.1.5)
Browse files Browse the repository at this point in the history
  • Loading branch information
@smintz
smintz committed Jan 17, 2022
1 parent 124594e commit 9613920
Show file tree
Hide file tree
Showing 3 changed files with 175 additions and 79 deletions.
2 changes: 1 addition & 1 deletion docs/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
### On Linux/MacOS

```
export PROTOCONF_VERSION="0.1.4"
export PROTOCONF_VERSION="0.1.5"
export PROTOCONF_OS=$(uname | tr '[A-Z]' '[a-z]')
# change to "arm64" if needed
export PROTOCONF_ARCH="amd64"
Expand Down
166 changes: 111 additions & 55 deletions docs/integrations/terraform.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,51 +20,85 @@ provider "tls" {}
$ terraform init
```

### Copy all providers binaries to same directory

```shell
$ find .terraform -type f -exec cp {} .terraform \;
```

### Generate the terraform protos

```shell
$ protoconf import terraform -import_path .terraform
$ protoconf import terraform
```

Validate the outpus
Validate the outputs

```shell
$ ll src/terraform
total 48K
drwxr-xr-x 10 smintz 320 May 23 10:46 .
drwxr-xr-x 3 smintz 96 May 23 10:39 ..
-rw-r--r-- 1 smintz 461 May 23 10:46 meta.proto
-rw-r--r-- 1 smintz 51 May 23 10:46 random-data.proto
-rw-r--r-- 1 smintz 371 May 23 10:46 random-provider.proto
-rw-r--r-- 1 smintz 8.1K May 23 10:46 random-resources.proto
-rw-r--r-- 1 smintz 4.5K May 23 10:46 terraform.proto
-rw-r--r-- 1 smintz 1.9K May 23 10:46 tls-data.proto
-rw-r--r-- 1 smintz 362 May 23 10:46 tls-provider.proto
-rw-r--r-- 1 smintz 6.1K May 23 10:46 tls-resources.proto
$ find src/terraform
src/terraform
src/terraform/v1
src/terraform/v1/terraform.proto
src/terraform/v1/meta.proto
src/terraform/tls
src/terraform/tls/datasources
src/terraform/tls/datasources/v3
src/terraform/tls/datasources/v3/public.proto
src/terraform/tls/datasources/v3/certificate.proto
src/terraform/tls/resources
src/terraform/tls/resources/v3
src/terraform/tls/resources/v3/private.proto
src/terraform/tls/resources/v3/self.proto
src/terraform/tls/resources/v3/cert.proto
src/terraform/tls/resources/v3/locally.proto
src/terraform/tls/provider
src/terraform/tls/provider/v3
src/terraform/tls/provider/v3/tls.proto
src/terraform/random
src/terraform/random/resources
src/terraform/random/resources/v3
src/terraform/random/resources/v3/password.proto
src/terraform/random/resources/v3/integer.proto
src/terraform/random/resources/v3/string.proto
src/terraform/random/resources/v3/pet.proto
src/terraform/random/resources/v3/shuffle.proto
src/terraform/random/resources/v3/id.proto
src/terraform/random/resources/v3/uuid.proto
src/terraform/random/provider
src/terraform/random/provider/v3
src/terraform/random/provider/v3/random.proto
```

The `src/terraform/terraform.proto` should looks like this:

```proto
syntax = "proto3";
package terraform;
package terraform.v1;
import "terraform/random/provider/v3/random.proto";
import "terraform/random/resources/v3/id.proto";
import "terraform/random/resources/v3/integer.proto";
import "terraform/random/resources/v3/password.proto";
import "terraform/random/resources/v3/pet.proto";
import "terraform/random/resources/v3/shuffle.proto";
import "terraform/random/resources/v3/string.proto";
import "terraform/random/resources/v3/uuid.proto";
import "terraform/tls/datasources/v3/certificate.proto";
import "terraform/random-provider.proto";
import "terraform/tls/datasources/v3/public.proto";
import "terraform/random-resources.proto";
import "terraform/tls/provider/v3/tls.proto";
import "terraform/tls-data.proto";
import "terraform/tls/resources/v3/cert.proto";
import "terraform/tls-provider.proto";
import "terraform/tls/resources/v3/locally.proto";
import "terraform/tls-resources.proto";
import "terraform/tls/resources/v3/private.proto";
import "terraform/tls/resources/v3/self.proto";
message Terraform {
Resources resource = 1;
Expand All @@ -84,39 +118,39 @@ message Terraform {
TerraformSettings terraform = 8;
message Resources {
map<string, random.resources.RandomId> random_id = 1 [json_name = "random_id"];
map<string, terraform.random.resources.v3.RandomId> random_id = 1 [json_name = "random_id"];
map<string, random.resources.RandomInteger> random_integer = 2 [json_name = "random_integer"];
map<string, terraform.random.resources.v3.RandomInteger> random_integer = 2 [json_name = "random_integer"];
map<string, random.resources.RandomPassword> random_password = 3 [json_name = "random_password"];
map<string, terraform.random.resources.v3.RandomPassword> random_password = 3 [json_name = "random_password"];
map<string, random.resources.RandomPet> random_pet = 4 [json_name = "random_pet"];
map<string, terraform.random.resources.v3.RandomPet> random_pet = 4 [json_name = "random_pet"];
map<string, random.resources.RandomShuffle> random_shuffle = 5 [json_name = "random_shuffle"];
map<string, terraform.random.resources.v3.RandomShuffle> random_shuffle = 5 [json_name = "random_shuffle"];
map<string, random.resources.RandomString> random_string = 6 [json_name = "random_string"];
map<string, terraform.random.resources.v3.RandomString> random_string = 6 [json_name = "random_string"];
map<string, random.resources.RandomUuid> random_uuid = 7 [json_name = "random_uuid"];
map<string, terraform.random.resources.v3.RandomUuid> random_uuid = 7 [json_name = "random_uuid"];
map<string, tls.resources.TlsCertRequest> tls_cert_request = 8 [json_name = "tls_cert_request"];
map<string, terraform.tls.resources.v3.TlsCertRequest> tls_cert_request = 8 [json_name = "tls_cert_request"];
map<string, tls.resources.TlsLocallySignedCert> tls_locally_signed_cert = 9 [json_name = "tls_locally_signed_cert"];
map<string, terraform.tls.resources.v3.TlsLocallySignedCert> tls_locally_signed_cert = 9 [json_name = "tls_locally_signed_cert"];
map<string, tls.resources.TlsPrivateKey> tls_private_key = 10 [json_name = "tls_private_key"];
map<string, terraform.tls.resources.v3.TlsPrivateKey> tls_private_key = 10 [json_name = "tls_private_key"];
map<string, tls.resources.TlsSelfSignedCert> tls_self_signed_cert = 11 [json_name = "tls_self_signed_cert"];
map<string, terraform.tls.resources.v3.TlsSelfSignedCert> tls_self_signed_cert = 11 [json_name = "tls_self_signed_cert"];
}
message Datasources {
map<string, tls.data.TlsCertificate> tls_certificate = 1 [json_name = "tls_certificate"];
map<string, terraform.tls.datasources.v3.TlsCertificate> tls_certificate = 1 [json_name = "tls_certificate"];
map<string, tls.data.TlsPublicKey> tls_public_key = 2 [json_name = "tls_public_key"];
map<string, terraform.tls.datasources.v3.TlsPublicKey> tls_public_key = 2 [json_name = "tls_public_key"];
}
message Providers {
repeated random.provider.Random random = 1;
repeated terraform.random.provider.v3.Random random = 1;
repeated tls.provider.Tls tls = 2;
repeated terraform.tls.provider.v3.Tls tls = 2;
}
message Variable {
Expand All @@ -137,7 +171,7 @@ message Terraform {
message TerraformSettings {
string required_version = 1 [json_name = "required_version"];
map<string, Provider> required_providers = 2;
map<string, Provider> required_providers = 2 [json_name = "required_providers"];
Backend backend = 3;
Expand All @@ -151,7 +185,9 @@ message Terraform {
oneof config {
BackendLocal local = 1;
BackendS3 s3 = 2;
BackendRemote remote = 2;
BackendS3 s3 = 3;
}
message BackendLocal {
Expand All @@ -160,6 +196,28 @@ message Terraform {
string workspace_dir = 2 [json_name = "workspace_dir"];
}
message BackendRemote {
//(Optional) The remote backend hostname to connect to. Defaults to app.terraform.io.
string hostname = 1;
//(Required) The name of the organization containing the targeted workspace(s).
string organization = 2;
//(Optional) The token used to authenticate with the remote backend. We recommend omitting the token from the configuration, and instead using `terraform login` or manually configuring `credentials` in the CLI config file.
string token = 3;
//(Required) A block specifying which remote workspace(s) to use. The workspaces block supports the following keys
Workspace workspaces = 4;
message Workspace {
//(Optional) The full name of one remote workspace. When configured, only the default workspace can be used. This option conflicts with prefix.
string name = 1;
//(Optional) A prefix used in the names of one or more remote workspaces, all of which can be used with this configuration. The full workspace names are used in Terraform Cloud, and the short names (minus the prefix) are used on the command line for Terraform CLI workspaces. If omitted, only the default workspace can be used. This option conflicts with name.
string prefix = 2;
}
}
message BackendS3 {
string region = 1;
Expand Down Expand Up @@ -233,9 +291,9 @@ message Terraform {
```python
# vim: filetype=python
# ./src/tfdemo/tfdemo.tf.pconf
load("//terraform/terraform.proto", "Terraform")
load("//terraform/random-provider.proto", "Random")
load("//terraform/random-resources.proto", "RandomPet")
load("//terraform/v1/terraform.proto", "Terraform")
load("//terraform/random/provider/v3/random.proto", "Random")
load("//terraform/random/resources/v3/pet.proto", "RandomPet")

tf = Terraform(
provider=Terraform.Providers(random=[Random()]),
Expand All @@ -260,7 +318,7 @@ $ protoconf compile .
Check the output

```shell
cat materialized_config/tfdemo/tfdemo.tf.materialized_JSON| jq
cat materialized_config/tfdemo/tfdemo.tf.materialized_JSON
```

```json
Expand All @@ -274,9 +332,7 @@ cat materialized_config/tfdemo/tfdemo.tf.materialized_JSON| jq
}
},
"provider": {
"random": [
{}
]
"random": [{}]
},
"resource": {
"random_pet": {
Expand All @@ -292,11 +348,11 @@ cat materialized_config/tfdemo/tfdemo.tf.materialized_JSON| jq
```shell
$ mkdir tf
$ cat materialized_config/tfdemo/tfdemo.tf.materialized_JSON | jq '.value | del(.["@type"])' > tf/test.tf.json
$ cd tf
$ terraform init
$ terraform -chdir=tf init
```

```shell
$ terraform plan
$ terraform -chdir=tf plan

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
Expand All @@ -322,8 +378,9 @@ Note: You didn't specify an "-out" parameter to save this plan, so Terraform
can't guarantee that exactly these actions will be performed if
"terraform apply" is subsequently run.
```
```shell
$ terraform apply -auto-approve
$ terraform -chdir=tf apply -auto-approve
random_pet.my_dog_name: Creating...
random_pet.my_dog_name: Creation complete after 0s [id=key-zebra]

Expand All @@ -333,4 +390,3 @@ Outputs:

my_dog_name = "key-zebra"
```

0 comments on commit 9613920

Please sign in to comment.