ascode/_documentation/getting-started.md

title	weight
Getting Started	2

This page explains the basics of using AsCode to define your infrastructure in Terraform. It assumes that you have already installed Ascode.

> ascode --help
Usage:
  ascode [OPTIONS] <repl | run | version>

AsCode - Terraform Alternative Syntax.

Help Options:
  -h, --help  Show this help message

Available commands:
  repl     Run as interactive shell.
  run      Run parses, resolves, and executes a Starlark file.
  version  Version prints information about this binary.

The repl command

The repl command provides a handy REPL interface for debugging and tinkering with AsCode.

For example you can explore the API of a resource printing the list of arguments:

> ascode repl
>>> print(dir(helm.resource))
["__kind__", "__provider__", "release", "repository"]

Or to validate how a resource will be rendered:

> ascode repl
>>> aws = tf.provider("aws")
>>> web = aws.resource.instance("web", instance_type="t2.micro")
>>> print(hcl(web))
resource "aws_instance" "web" {
  provider      = aws.id_01E4JV722PS2WPKK7WQ2NMZY6D
  instance_type = "t2.micro"
}

The run command

The run command executes a valid Starlack program. Using the --print-hcl and --to-hcl, an HCL encoded version of the tf object will be printed or saved to a given file, respectively.

This is the first step to deploy any infrastructure d defined with AsCode, using run and generating a valid .tf file, we can use the standard Terraform tooling to deploy our infrastructure using terraform init, terraform plan and terraform apply.

To learn about writing Starlark programs, please refer to the Language definition and the API Reference sections of this documentation.

Basic Example

The goal of the example is create, in DigitalOcean, one s-1vcpu-1gb instance called web in the nyc2 region:

For running this example, you need terraform correctly installed on your system.

> mkdir example; cd example
> echo 'do = tf.provider("digitalocean")' > main.star
> echo 'web = do.resource.droplet("web", name="web", size="s-1vcpu-1gb")' >> main.star
> echo 'web.region = "nyc2"' >> main.star
> echo 'web.image  = "ubuntu-18-04-x64"' >> main.star

Now we are ready to run our Starlark program and generate a valid HCL file:

> ascode run main.star --to-hcl main.tf
> cat main.tf
provider "digitalocean" {
  alias   = "id_01E4JXQD8HKW7XEQ7R5S8SP8AQ"
  version = "1.15.1"
}

resource "digitalocean_droplet" "web" {
  provider = digitalocean.id_01E4JXQD8HKW7XEQ7R5S8SP8AQ
  image    = "ubuntu-18-04-x64"
  name     = "web"
  region   = "nyc2"
  size     = "s-1vcpu-1gb"
}

And now as it's common in terraform we can run init, plan or/and apply

> terraform init
...
> terraform plan
Terraform will perform the following actions:

  # digitalocean_droplet.web will be created
  + resource "digitalocean_droplet" "web" {
      + backups              = false
      + disk                 = (known after apply)
      + id                   = (known after apply)
      + image                = "ubuntu-18-04-x64"
      + ipv4_address         = (known after apply)
      + ipv4_address_private = (known after apply)
      + ipv6                 = false
      + ipv6_address         = (known after apply)
      + ipv6_address_private = (known after apply)
      + locked               = (known after apply)
      + memory               = (known after apply)
      + monitoring           = false
      + name                 = "web"
      + price_hourly         = (known after apply)
      + price_monthly        = (known after apply)
      + private_networking   = false
      + region               = "nyc2"
      + resize_disk          = true
      + size                 = "s-1vcpu-1gb"
      + status               = (known after apply)
      + urn                  = (known after apply)
      + vcpus                = (known after apply)
      + volume_ids           = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

> terraform apply
...

The version command

The version command prints a report about the versions of the different dependencies, and AsCode itself used to compile the binary.

> ascode version
Go Version: go1.14.1
AsCode Version: v0.0.1
AsCode Commit: 6a682e4
AsCode Build Date: 2020-03-29T12:43:52+02:00
Terraform Version: v0.12.23
Starlark Version: v0.0.0-20200306205701-8dd3e2ee1dd5