Skip to content

Commit

Permalink
Fix up installation docs (#666)
Browse files Browse the repository at this point in the history 
A section made it into the installation docs erroneously.
  • Loading branch information
@guineveresaenger
guineveresaenger authored Aug 21, 2024
2 parents 6c50b78 + 0c99bd1 commit b9ed4f7
Showing 1 changed file with 1 addition and 251 deletions.
252 changes: 1 addition & 251 deletions docs/installation-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -326,254 +326,4 @@ 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 Pulumi 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](https://docs.openstack.org/devstack/latest/) 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](https://github.com/gophercloud/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 Pulumi.
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 Pulumi 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](https://github.com/golang/go/wiki/Modules).

### Ad-hoc testing against existing cloud

If there is access to an existing cloud, developers can test changes on resources
against that cloud. In order to do so:
- Build the provider with your changes

Build locally the provider including your changes with:
```
go build .
```
this should generate a `pulumi-provider-openstack` binary.

- Remove the Pulumi Lock File

If there is already a pulumi lock file, remove it with:
```
rm .pulumi.lock.hcl
```

- Create or edit `.pulumi.rc` as shown below:

```
provider_installation {
dev_overrides {
"registry.pulumi.io/pulumi-provider-openstack/openstack" = "/path/to/directory/where/the/provider/binary/is"
}
direct {}
}
```
This configuration tells Pulumi to use the provider binary at the specified path
instead of the one from the Pulumi Registry. The direct {} block tells Pulumi
to use the provider from the Pulumi Registry if it’s not available locally.
Any other providers not specified in dev_overrides will still be downloaded from the
Pulumi Registry.

- Set Environment Variable for Pulumi Configuration

```
export TF_CLI_CONFIG_FILE=~/.pulumi.rc
```

- Run pulumi

```
❯ pulumi preview
│ Warning: Provider development overrides are in effect
│
│ The following provider development overrides are set in the CLI configuration:
│ - pulumi-provider-openstack/openstack in /path/to/directory/where/the/provider/binary/is
│
| The behavior may therefore not match any released version of the provider and applying changes may cause the state to become incompatible with published releases.
```

### 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:

* `OS_IMAGE_ID` or `OS_IMAGE_NAME` - a UUID or name of an existing image in
Glance.

* `OS_FLAVOR_ID` or `OS_FLAVOR_NAME` - an ID or name of an existing flavor.

* `OS_POOL_NAME` - The name of a Floating IP pool. In DevStack, this is
called `public` and you should set this value to the word `public`.

* `OS_NETWORK_ID` - The UUID of the private network in your test environment.
In DevStack, this network is called `private` and you should set this value
to the UUID of the `private` network.

* `OS_EXTGW_ID` - The UUID of the public network in your test environment. In
DevStack, this network is called `public` and you should set this value to
the UUID of the `public` network.

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

* `OS_DB_ENVIRONMENT` - Required if you're working on the `openstack_db_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_DB_DATASTORE_VERSION` - Required if you need to set a Trove/Database
datastore version.

* `OS_DB_DATASTORE_TYPE` - Required if you need to set a Trove/Database
datastore type.

* `OS_DNS_ENVIRONMENT` - Required if you're working on the `openstack_dns_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_SWIFT_ENVIRONMENT` - Required if you're working on an
`openstack_objectstorage_*` resource. Set this value to "1" to enable testing
these resources.

* `OS_LB_ENVIRONMENT` - Required if you're working on the `openstack_lb_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_FW_ENVIRONMENT` - Required if you're working on the `openstack_fw_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_VPN_ENVIRONMENT` - Required if you're working on the `openstack_vpn_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_SFS_ENVIRONMENT` - Required if you're working on the `openstack_sharedfilesystem_*`
resources. Set this value to "1" to enable testing these resources.

* `OS_HYPERVISOR_HOSTNAME` - Required if you're working on the `openstack_compute_hypervisor_v2`
data source. Set this value to one valid hypervisor hostname to test this data source.

* `OS_BGPVPN_ENVIRONMENT` - Required if you're working on the `openstack_bgpvpn_*`
resources. Set this value to "1" to enable testing these resources.

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

```shell
$ cd $GOPATH/src/github.com/pulumi-providers/pulumi-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:

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

We recommend running tests with logging set to `DEBUG`:

```shell
$ 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:

```shell
$ 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 `pulumi-provider-openstack`:

```shell
$ git remote add my-github-username https://github.com/my-github-username/pulumi-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/pulumi-provider-openstack/pulumi-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.
add any additional comments, please let us know.

0 comments on commit b9ed4f7

Please sign in to comment.