-
- v0.12 and higher (ACI Provider v1.0.0 or higher)
- v0.11.x or below (ACI Provider v0.7.1 or below)
-
Go Latest Version
Clone this repository to: $GOPATH/src/github.com/CiscoDevNet/terraform-provider-cisco-aci
.
$ mkdir -p $GOPATH/src/github.com/CiscoDevNet; cd $GOPATH/src/github.com/CiscoDevNet
$ git clone https://github.com/CiscoDevNet/terraform-provider-aci.git
Enter the provider directory and run dep ensure to install all the dependancies. After, that run make build to build the provider binary.
$ cd $GOPATH/src/github.com/CiscoDevNet/terraform-provider-aci
$ dep ensure
$ make build
If you are building the provider, follow the instructions to install it as a plugin. After placing it into your plugins directory, run terraform init
to initialize it.
ex.
terraform {
required_providers {
aci = {
source = "ciscodevnet/aci"
}
}
}
#configure provider with your cisco aci credentials.
provider "aci" {
# cisco-aci user name
username = "admin"
# cisco-aci password
password = "password"
# cisco-aci url
url = "https://my-cisco-aci.com"
insecure = true
proxy_url = "https://proxy_server:proxy_port"
}
resource "aci_tenant" "test-tenant" {
name = "test-tenant"
description = "This tenant is created by terraform"
}
resource "aci_application_profile" "test-app" {
tenant_dn = aci_tenant.test-tenant.id
name = "test-app"
description = "This application profile is created by terraform"
}
Note : If you are facing the issue of invalid character '<' looking for beginning of value
while running terraform apply
, use signature based authentication in that case, or else use -parallelism=1
with terraform plan
and terraform apply
to limit the concurrency to one thread.
terraform plan -parallelism=1
terraform apply -parallelism=1
provider "aci" {
# cisco-aci user name
username = "admin"
# private key path
private_key = "path to private key"
# Certificate Name
cert_name = "user-cert"
# cisco-aci url
url = "https://my-cisco-aci.com"
insecure = true
}
Note: The value of "cert_name" argument must match the name of the certificate object attached to the APIC user (aaaUserCert) used for signature-based authentication
Currently the ACI provider is a muxed provider which allows us to simultaneously serve terraform-plugin-sdk/v2 and terraform-plugin-framework provider SDK implementations. This adds some complexity to the development process, but allows us to leverage the new capabilities that terraform-plugin-framework provides, while working on a migration strategy for existing resources.
- Install latest version of Go
-
Existing resources and data-sources are located in the aci directory.
-
Changes are made directly in the
provider.go
,resource_*.go
,data_source_*.go
andutils
files. The aci-go-client is leveraged to construct payload constructs and handle REST communication towards the APIC. -
Documentation is manually maintained in the legacy-docs directory and are copied automatically up on execution of
go generate
command. -
Examples are manually maintained in the examples directory, where each resource has it's own directory.
The below steps should be followed for developing terraform-plugin-sdk/v2
resources and data-sources:
-
Create issue (if not created yet) and comment that you will be working on the issue.
-
Fork the terraform-provider-aci repository.
-
Clone the forked code to your local machine.
-
Make changes to the files manually.
- Code changes
- Examples changes
- Documentation changes
-
Run
go generate
in the root of the local repository where themain.go
is located. Assure that the documentation is copied to the docs folder and no changes are made to files in the internal/provider directory. -
Test the code.
-
Create PR for the code and request review from active maintainers.
-
Review process
-
New resources and data-sources are located in the internal/provider directory.
-
The
provider.go
,resource_*.go
,resource_*_test.go
,data_source_*.go
,data_source_*_test.go
are generated with templates and should not be changed manually. Files that are automatically generated start with// Code generated by "gen/generator.go"; DO NOT EDIT.
and should not be modified. When a file is not generated correctly, the template of that file must be adjusted. -
Examples used in the documentation are generated automatically and stored in the examples/resources and examples/data-sources directories.
-
Documentation for resources and datasources are generated automatically and stored in the docs directory.
-
There are a few exceptions of static files which need to be changed manually:
- Files related to
rest_managed
- provider_test.go
- provider.tf
- Files related to
New resources and data-sources are generated with generator.go. The generator assumes that the following directories exist in the directory where the generate.go file is located:
-
./definitions
- contains the manually created YAML files with the ACI class definitions for overwriting the meta data retrieved from APIC
-
./meta
- contains the JSON files with the ACI class metadata which are retrieved from APIC
-
./templates
- contains the Go templates used to generate the full provider code
-
./testvars
- contains the generated YAML files with the test variables used in the *_test.go and example files
The below steps should be followed for developing terraform-plugin-framework
resources and data-sources:
-
Create issue and comment that you will be working on the issue.
-
Fork the terraform-provider-aci repository.
-
Clone the forked code to your local machine.
-
Add minimum required class details to classes.yaml.
ui_location
sub_category
- Copy new meta file(s) or replace existing with newer version of the meta file(s) to the meta directory in the following format:
<classname>.json
. Assure that all relationship classes are also added to themeta
directory. TheGEN_HOST
andGEN_CLASSES
environment variables can be leveraged to retrieve the classes automatically before rendering the code.
GEN_HOST
can be set to a resolvable APIC host, example:192.158.1.38
. When not provided the devnet documentation will be retrieved.GEN_CLASSES
should be set to a comma-separated string of classes, example:fvTenant
orfvTenant,fvBD
- Run
go generate
in the root of the local repository where themain.go
is located. The following files should be created or updated:
resource_<resource-name>.go
andresource_<resource-name>_test.go
data_source_<resource-name>.go
anddata_source_<resource-name>_test.go
<resource-name>.md
in the docs/resources and docs/data-sources directories.resource.tf
anddata-source.tf
provider.go
- Validate generated files generated on the following items:
- resource name
- incorrect resource names should be overwritten in classes.yaml by providing
resource_name: "<resource-name>"
- incorrect resource names should be overwritten in classes.yaml by providing
- schema attributes ( class properties and children )
- incorrect property names should be overwritten in properties.yaml by providing a global or class specific overwrite
- all relationships classes are included
- documentation contains the example and all information is correct
- Run
go generate
again until the files are generated as preferred. When you are not achieving the desired outputs, reource, data-source, example and/or documentation templates should be adjusted.
- Test the generated code of your resources and data-sources
- Execute the tests for all your generated resources and data-sources
- Set the below environment variables when running tests:
export ACI_VAL_REL_DN=false export TF_ACC=1 export ACI_USERNAME="USER" export ACI_URL="https://IPADDRESS" export ACI_PASSWORD="PASSWORD"
- The following command can be used
go test internal/provider/* -v -run <test-name>
, where the test name can be found in theresource_<resource-name>_test.go
anddata_source_<resource-name>_test.go
files. - Adjust generated test_values in case incorrect values are used. All test values are resolved by estimating the values. Some values are hard to resolve with and thus need to be overwritten in properties.yaml file under the class specific test_values.
- Some tests have a dependency on a specific parent, which is unknown because the resource is not an autogenerated resource yet. This can be set in the properties.yaml file under the the class specific parents.
- Run
go generate
again until the files are generated as preferred. When you are not achieving the desired outputs, the test templates should be adjusted.
-
Create PR for the code and request review from active maintainers.
-
Review process
If you encounter an error message while generating the resources using go generate, a few steps can be followed:
-
Make sure that you're running the latest version of Go
-
Update dependencies and populate the vendor directory: If you're using Go modules, you can update your dependencies and populate your vendor directory by running the following commands in your terminal:
go mod tidy
go mod vendor
The go mod tidy command will clean up unused dependencies and add missing ones. The go mod vendor command will copy all dependencies into the vendor directory.
- Disable vendor mode (if necessary): If the error still persists, consider disabling vendor mode by setting GOFLAGS="-mod=mod", and then run go get again:
export GOFLAGS="-mod=mod"
This will force Go to fetch the package directly, regardless of the vendor directory. After the package is downloaded, you can switch back to vendor mode if needed.
If you encounter an error indicating that the golang.org/x/text/language package is missing from your vendor directory, you can fetch it by following these steps:
- Disable vendor mode: Go operates in vendor mode when the -mod=vendor flag is set. You'll need to disable vendor mode to fetch packages directly. Run the following command in your terminal:
export GOFLAGS="-mod=mod"
- Fetch the missing package: Now that vendor mode is disabled, you can fetch the missing package by running:
go get golang.org/x/text/language
This command tells Go to fetch the golang.org/x/text/language package directly, regardless of the vendor directory
- Re-enable vendor mode (if necessary): If you wish to switch back to vendor mode, you can do so by running:
export GOFLAGS="-mod=vendor"
To compile the provider, run make build
. This will build the provider with sanity checks present in scripts directory and put the provider binary in $GOPATH/bin
directory.
Important: To successfully use the provider you need to follow these steps:
-
Copy or Symlink the provider from the
$GOPATH/bin
to~/.terraform.d/plugins/terraform.local/CiscoDevNet/aci/<Version>/<architecture>/
for example:ln -s ~/go/bin/terraform-provider-aci ~/.terraform.d/plugins/terraform.local/CiscoDevNet/aci/2.3.0/linux_amd64/terraform-provider-aci
-
Edit the Terraform Provider Configuration to use the local provider.
terraform { required_providers { aci = { source = "terraform.local/CiscoDevNet/aci" version = "2.3.0" } } }
NOTE: Currently only resource properties supports the reflecting manual changes made in CISCO ACI. Manual changes to relationship is not taken care by the provider.