diff --git a/docs/end-user/cloud-resources.md b/docs/end-user/cloud-resources.md index 9299d6a3..b7466013 100644 --- a/docs/end-user/cloud-resources.md +++ b/docs/end-user/cloud-resources.md @@ -1,5 +1,5 @@ --- -title: Provision and Consume Cloud Resources +title: Provision and Consume Cloud Resources by Crossplane --- > ⚠️ This section requires your platform builder has already installed the [cloud resources related capabilities](../platform-engineers/cloud-services). diff --git a/docs/end-user/terraform.md b/docs/end-user/terraform.md new file mode 100644 index 00000000..1d0ebd7c --- /dev/null +++ b/docs/end-user/terraform.md @@ -0,0 +1,104 @@ +--- +title: Provision and Consume Cloud Resources by Terraform +--- + +> ⚠️ This section requires your platform builder has already installed the [Terraform related capabilities](../platform-engineers/terraform.md). + +Check the parameters of cloud resource components and trait. + +```shell +$ kubectl vela show alibaba-rds +# Properties ++----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+ +| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT | ++----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+ +| bucket | OSS bucket name | string | true | | +| acl | OSS bucket ACL, supported 'private', 'public-read', 'public-read-write' | string | true | | +| writeConnectionSecretToRef | The secret which the cloud resource connection will be written to | [writeConnectionSecretToRef](#writeConnectionSecretToRef) | false | | ++----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+ + + +## writeConnectionSecretToRef ++-----------+-----------------------------------------------------------------------------+--------+----------+---------+ +| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT | ++-----------+-----------------------------------------------------------------------------+--------+----------+---------+ +| name | The secret name which the cloud resource connection will be written to | string | true | | +| namespace | The secret namespace which the cloud resource connection will be written to | string | false | | ++-----------+-----------------------------------------------------------------------------+--------+----------+---------+ + + +$ kubectl vela show service-binding +# Properties ++-------------+------------------------------------------------+------------------+----------+---------+ +| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT | ++-------------+------------------------------------------------+------------------+----------+---------+ +| envMappings | The mapping of environment variables to secret | map[string]{...} | true | | ++-------------+------------------------------------------------+------------------+----------+---------+ +``` + +Now apply an [application](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/application.yaml) as below. + +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: webapp +spec: + components: + - name: express-server + type: webservice + properties: + image: zzxwill/flask-web-application:v0.3.1-crossplane + ports: 80 + traits: + - type: service-binding + properties: + envMappings: + # environments refer to db-conn secret + DB_PASSWORD: + secret: db-conn # 1) If the env name is the same as the secret key, secret key can be omitted. + endpoint: + secret: db-conn + key: DB_HOST # 2) If the env name is different from secret key, secret key has to be set. + username: + secret: db-conn + key: DB_USER + # environments refer to oss-conn secret + BUCKET_NAME: + secret: oss-conn + + - name: sample-db + type: alibaba-rds + properties: + instance_name: sample-db + account_name: oamtest + password: U34rfwefwefffaked + writeConnectionSecretToRef: + name: db-conn + + - name: sample-oss + type: alibaba-oss + properties: + bucket: vela-website + acl: private + writeConnectionSecretToRef: + name: oss-conn + + +``` + +Apply it and verify the application. + +```shell +$ kubectl get application +NAME AGE +webapp 46m + +$ kubectl port-forward deployment/express-server 80:80 +Forwarding from 127.0.0.1:80 -> 80 +Forwarding from [::1]:80 -> 80 +Handling connection for 80 +Handling connection for 80 +``` + +![](../resources/crossplane-visit-application.jpg) diff --git a/docs/platform-engineers/cloud-services.md b/docs/platform-engineers/cloud-services.md index a1301c88..f6f64d01 100644 --- a/docs/platform-engineers/cloud-services.md +++ b/docs/platform-engineers/cloud-services.md @@ -126,7 +126,7 @@ metadata: name: alibaba-oss namespace: vela-system annotations: - definition.oam.dev/description: "Alibaba Cloud RDS Resource" + definition.oam.dev/description: "Alibaba Cloud OSS Resource" spec: workload: definition: diff --git a/docs/platform-engineers/terraform.md b/docs/platform-engineers/terraform.md new file mode 100644 index 00000000..f6880673 --- /dev/null +++ b/docs/platform-engineers/terraform.md @@ -0,0 +1,148 @@ +--- +title: Terraform +--- + +In addition to provisioning and consuming cloud resources by [Crossplane](./cloud-services.md), we can also use Terraform, +which is one of four ComponentDefinition schematic types `cue`, `kube`, `helm` and `terraform`. + +To enable end users to be able to create application by Terraform, please follow these steps. + +## Install Terraform Controller chart + +Download the latest chart, like `terraform-controller-chart-0.1.4.tgz`, from the latest [releases](https://github.com/oam-dev/terraform-controller/releases) and install it. + +```shell +$ helm install terraform-controller terraform-controller-0.1.2.tgz +NAME: terraform-controller +LAST DEPLOYED: Mon Apr 26 15:55:35 2021 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +For more detailed instruction, please refer to [Terraform controller getting started](https://github.com/oam-dev/terraform-controller/blob/master/getting-started.md). + +## Register ComponentDefinition and TraitDefinition + +### Register ComponentDefinition `alibaba-rds` as RDS cloud resource producer + +Register [alibaba-rds](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/ComponentDefinition-alibaba-rds.yaml) Component type to KubeVela. + +```yaml +apiVersion: core.oam.dev/v1alpha2 +kind: ComponentDefinition +metadata: + name: alibaba-rds + annotations: + definition.oam.dev/description: Terraform configuration for Alibaba Cloud RDS object + type: terraform +spec: + workload: + definition: + apiVersion: terraform.core.oam.dev/v1beta1 + kind: Configuration + schematic: + terraform: + configuration: | + module "rds" { + source = "terraform-alicloud-modules/rds/alicloud" + engine = "MySQL" + engine_version = "8.0" + instance_type = "rds.mysql.c1.large" + instance_storage = "20" + instance_name = var.instance_name + account_name = var.account_name + password = var.password + } + + output "DB_NAME" { + value = module.rds.this_db_instance_name + } + output "DB_USER" { + value = module.rds.this_db_database_account + } + output "DB_PORT" { + value = module.rds.this_db_instance_port + } + output "DB_HOST" { + value = module.rds.this_db_instance_connection_string + } + output "DB_PASSWORD" { + value = module.rds.this_db_instance_port + } + + variable "instance_name" { + description = "RDS instance name" + type = string + default = "poc" + } + + variable "account_name" { + description = "RDS instance user account name" + type = "string" + default = "oam" + } + + variable "password" { + description = "RDS instance account password" + type = "string" + default = "Xyfff83jfewGGfaked" + } + +``` + +### Register ComponentDefinition `alibaba-oss` as OSS cloud resource producer + +Register [alibaba-oss](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/ComponentDefinition-alibaba-oss.yaml) Component type to KubeVela. + + +```yaml +apiVersion: core.oam.dev/v1alpha2 +kind: ComponentDefinition +metadata: + name: alibaba-oss + annotations: + definition.oam.dev/description: Terraform configuration for Alibaba Cloud OSS object + type: terraform +spec: + workload: + definition: + apiVersion: terraform.core.oam.dev/v1beta1 + kind: Configuration + schematic: + terraform: + configuration: | + resource "alicloud_oss_bucket" "bucket-acl" { + bucket = var.bucket + acl = var.acl + } + + output "BUCKET_NAME" { + value = "${alicloud_oss_bucket.bucket-acl.bucket}.${alicloud_oss_bucket.bucket-acl.extranet_endpoint}" + } + + variable "bucket" { + description = "OSS bucket name" + default = "vela-website" + type = string + } + + variable "acl" { + description = "OSS bucket ACL, supported 'private', 'public-read', 'public-read-write'" + default = "private" + type = string + } + + +``` + +### Prepare TraitDefinition `service-binding` to do env-secret mapping + +Apply [service-binding](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/TraitDefinition-service-binding.yaml) to apply service binding trait. + +For more detailed introduction, please refer to [Crossplane](https://kubevela.io/docs/platform-engineers/cloud-services#prepare-traitdefinition-service-binding-to-do-env-secret-mapping). + + +## Next +Now You can refer to [Terraform for end users](../end-user/terraform.md) to provision and consume cloud resource by Terraform. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index a097ceda..e8246f44 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,6 +36,7 @@ module.exports = { 'end-user/labels', 'end-user/sidecar', 'end-user/cloud-resources', + 'end-user/terraform', 'end-user/volumes', 'end-user/monitoring', 'end-user/health', @@ -79,7 +80,8 @@ module.exports = { type: 'category', label: 'Defining Cloud Service', items: [ - 'platform-engineers/cloud-services' + 'platform-engineers/cloud-services', + 'platform-engineers/terraform', ] }, ]