OpenStack Provider

The OpenStack provider is used to interact with the many resources supported by OpenStack. The provider needs to be configured with the proper credentials before it can be used.

Use the navigation to the left to read about the available resources.

Example Usage

# Define required providers
terraform {
required_version = ">= 0.14.0"
  required_providers {
    openstack = {
      source  = "terraform-provider-openstack/openstack"
      version = "~> 1.53.0"
    }
  }
}

# Configure the OpenStack Provider
provider "openstack" {
  user_name   = "admin"
  tenant_name = "admin"
  password    = "pwd"
  auth_url    = "http://myauthurl:5000/v3"
  region      = "RegionOne"
}

# Create a web server
resource "openstack_compute_instance_v2" "test-server" {
  # ...
}

Configuration Reference

The following arguments are supported:

Overriding Service API Endpoints

There might be a situation in which you want or need to override an API endpoint rather than use the endpoint which was returned to you in the service catalog. You can do this by configuring the endpoint_overrides argument in the provider configuration:

provider "openstack" {

  endpoint_overrides = {
    "network"  = "https://example.com:9696/v2.0/"
    "volumev2" = "https://volumes.example.com:8776/v2/3eb25ae78e7b42d68276e9bca66c8e44/"
  }

}

Note how each URL ends in a "/" and the volumev2 service includes the tenant/project UUID. You must make sure you specify the full and complete endpoint URL for this to work.

The service keys are the standard service entries used in the OpenStack Identity/Keystone service catalog. This provider supports:

Please use this feature at your own risk. If you are unsure about needing to override an endpoint, you most likely do not need to override one.

Additional Logging

This provider has the ability to log all HTTP requests and responses between Terraform and the OpenStack cloud which is useful for troubleshooting and debugging.

To enable these logs, set the OS_DEBUG environment variable to 1 along with the usual TF_LOG=DEBUG environment variable:

$ OS_DEBUG=1 TF_LOG=DEBUG terraform apply

If you submit these logs with a bug report, please ensure any sensitive information has been scrubbed first!

OpenStack Releases and Versions

This provider aims to support "vanilla" OpenStack. This means that we do all testing and development using the official upstream OpenStack code. If your OpenStack environment has patches or modifications, we do our best to accommodate these modifications, but we can't guarantee this.

We try to support _all_ releases of OpenStack when we can. If your OpenStack cloud is running an older release, we still should be able to support it.

Octavia api versioning

Octavia api is using minor versions when adding new features and functionality. The required minor version of each feature are documented on the resource page. When using such a feature ensure that your Openstack cloud supports the required minor version. A simple way of checking which minor versions are supported on your Openstack cloud is the following:

export OS_TOKEN=`openstack token issue -c id -f value`
curl -s -H "X-Auth-Token: $OS_TOKEN"  "https://example.com:9876/"

Rackspace Compatibility

Using this OpenStack provider with Rackspace is not supported and not guaranteed to work; however, users have reported success with the following notes in mind:

provider "openstack" {
  user_name = "your-username"
  password  = "your-password"
  tenant_id = "your-tenant-id"
  region    = "IAD"
  auth_url  = "https://identity.api.rackspacecloud.com/v2.0/"
  endpoint_overrides = {
    "network" = "https://iad.networks.api.rackspacecloud.com/v2.0/"
  }
}
resource "openstack_compute_instance_v2" "my_instance" {
  name      = "my_instance"
  region    = "DFW"
  image_id  = "fabe045f-43f8-4991-9e6c-5cabd617538c"
  flavor_id = "general1-4"
  key_pair  = "provisioning_key"

  network {
    uuid = "00000000-0000-0000-0000-000000000000"
    name = "public"
  }

  network {
    uuid = "11111111-1111-1111-1111-111111111111"
    name = "private"
  }
}

If you try using this provider with Rackspace and run into bugs, you are welcomed to open a bug report / issue on Github, but please keep in mind that this is unsupported and the reported bug may not be able to be fixed.

If you have successfully used this provider with Rackspace and can add any additional comments, please let us know.

Testing and Development

Thank you for your interest in further developing the OpenStack provider! Here are a few notes which should help you get started. If you have any questions or feel these notes need further details, please open an Issue and let us know.

Coding and Style

This provider aims to adhere to the coding style and practices used in the other major Terraform Providers. However, this is not a strict rule.

We're very mindful that not everyone is a full-time developer (most of the OpenStack Provider contributors aren't!) and we're happy to provide guidance. Don't be afraid if this is your first contribution to the OpenStack provider or even your first contribution to an open source project!

Testing Environment

In order to start fixing bugs or adding features, you need access to an OpenStack environment. If it is safe to do, you can use a production OpenStack cloud which you have access to. However, it's usually safer to work in a development cloud.

DevStack is a quick and easy way to spin up an OpenStack cloud. All OpenStack services have DevStack plugins so you can build a DevStack environment to test everything from Nova/Compute to Designate/DNS.

Fully configuring a DevStack installation is outside the scope of this document; however, we'll try to provide assistance where we can.

Gophercloud

This provider uses Gophercloud as the Go OpenStack SDK. All API interaction between this provider and an OpenStack cloud is done exclusively with Gophercloud.

Adding a Feature

If you'd like to add a new feature to this provider, it must first be supported in Gophercloud. If Gophercloud is missing the feature, then it'll first have to be added there before you can start working on the feature in Terraform. Fortunately, most of the regular OpenStack Provider contributors also work on Gophercloud, so we can try to get the feature added quickly.

If the feature is already included in Gophercloud, then you can begin work directly in the OpenStack provider.

If you have any questions about whether Gophercloud currently supports a certain feature, please feel free to ask and we can verify for you.

Fixing a Bug

Similarly, if you find a bug in this provider, the bug might actually be a Gophercloud bug. If this is the case, then we'll need to get the bug fixed in Gophercloud first.

However, if the bug is with Terraform itself, then you can begin work directly in the OpenStack provider.

Again, if you have any questions about whether the bug you're trying to fix is a Gophercloud but, please ask.

Dependencies

If you require pulling in changes from an external package, such as Gophercloud, this provider uses Go Modules.

Acceptance Tests

Acceptance Tests are a crucial part of adding features or fixing a bug. Please make sure to read the core testing documentation for more information about how Acceptance Tests work.

In order to run the Acceptance Tests, you'll need to set the following environment variables:

The following additional environment variables might be required depending on the feature or bug you're testing:

We recommend only running the acceptance tests related to the feature or bug you're working on. To do this, run:

$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-openstack
$ make testacc TEST=./openstack TESTARGS="-run=<keyword> -count=1"

Where <keyword> is the full name or partial name of a test. For example:

$ make testacc TEST=./openstack TESTARGS="-run=TestAccComputeV2Keypair_basic -count=1"

We recommend running tests with logging set to DEBUG:

$ TF_LOG=DEBUG make testacc TEST=./openstack TESTARGS="-run=TestAccComputeV2Keypair_basic -count=1"

And you can even enable OpenStack debugging to see the actual HTTP API requests:

$ TF_LOG=DEBUG OS_DEBUG=1 make testacc TEST=./openstack TESTARGS="-run=TestAccComputeV2Keypair_basic -count=1"

Creating a Pull Request

When you're ready to submit a Pull Request, create a branch, commit your code, and push to your forked version of terraform-provider-openstack:

$ git remote add my-github-username https://github.com/my-github-username/terraform-provider-openstack
$ git checkout -b my-feature
$ git add .
$ git commit
$ git push -u my-github-username my-feature

Then navigate to https://github.com/terraform-provider-openstack/terraform-provider-openstack and create a Pull Request.

Testing with GitHub Actions

Once you have created a Pull Request, it will automatically be tested by various GitHub Actions. GitHub Actions use Devstack to create a clean vanilla Openstack Cloud. Multiple jobs are triggered to test various versions of Openstack as well as different services. Testing will take between 90-120 minutes and you will receive a notification with a test report when testing has finished.

If there were any failures, check the provided logs.

There are a few reasons for test failures:

  1. Your code changes worked in your environment but are not working in a different OpenStack environment.

  2. Your code changes caused another test to fail.

  3. DevStack is having issues.

If you are unable to determine why the failures happened, please ask and we'll look into the cause.