You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add some more detailed instructions on how to write code for the provider. This is more of a starting point which can be extended further. The goal is to have a basic guidance for anyone new to the provider development: Which plugin to use, which resource to use as a baseline example, etc.
env TF_LOG=DEBUG make docker-testacc TESTARGS='-run ^TestAccResourceDataStreamLifecycle$$'
19
-
```
17
+
* Create a new branch for your changes.
18
+
* Make your changes. See [Useful Commands](#useful-commands) and [Debugging](#running--debugging-the-provider).
19
+
* Validate your changes
20
+
* Run unit and acceptance tests (See [Running Acceptance Tests](#running-acceptance-tests)).
21
+
* Run `make lint` to check linting and formatting. For this check to succeed, all changes must have been committed.
22
+
* All checks also run automatically on every PR.
23
+
* Submit your PR for review.
24
+
* Add a changelog entry in `CHANGELOG.md` under the `Unreleased` section. This will be included in the release notes of the next release. The changelog entry references the PR, so it has to be added after the PR has been opened.
20
25
21
-
A way to forward debug logs to a file:
22
-
```bash
23
-
env TF_ACC_LOG_PATH=/tmp/tf.log TF_ACC_LOG=DEBUG TF_LOG=DEBUG make docker-testacc
24
-
```
26
+
When creating new resources:
27
+
* Use the [Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework/getting-started/code-walkthrough) for new resources.
28
+
* Use an existing resource (e.g. `internal/elasticsearch/security/system_user`) as a template.
29
+
* Some resources use the deprecated Terraform SDK, so only resources using the new Terraform Framework should be used as reference.
30
+
* Use the generated API clients to interact with the Kibana APIs. (See [Working with Generated API Clients](#working-with-generated-api-clients)
31
+
* Add a documentation template and examples for the resource. See [Updating Documentation](#updating-documentation) for more details.
32
+
* Write unit and acceptance tests.
25
33
34
+
### Useful Commands
26
35
27
-
## Update documentation
36
+
*`make build`: Build the provider.
37
+
*`make lint`: Lints and formats the code.
38
+
*`make test`: Run unit tests.
39
+
*`make docs-generate`: Generate documentation.
40
+
*[Running & Debugging the Provider](#running--debugging-the-provider)
Update documentation templates in `./templates` directory and re-generate docs via:
30
-
```bash
31
-
make docs-generate
32
-
```
43
+
### Running & Debugging the Provider
33
44
34
-
## Update `./CHANGELOG.md`
45
+
You can run the currently checked-out code for local testing and use it with Terraform.
35
46
36
-
List of previous commits is a good example of what should be included in the changelog.
47
+
Also see [Terraform docs on debugging](https://developer.hashicorp.com/terraform/plugin/debugging#starting-a-provider-in-debug-mode).
37
48
49
+
Run the provider in debug mode and reattach the provider in Terraform:
50
+
* Launch `main.go` with the `-debug` flag from your IDE.
51
+
* Or launch it with `go run main.go -debug` from the command line.
52
+
* After launching, the provider will print an env var. Copy the printed `TF_REATTACH_PROVIDERS='{…}'` value.
53
+
* Export it in your shell where you run Terraform: `export TF_REATTACH_PROVIDERS='{…}'`.
54
+
* Terraform will now talk to your debug instance, and you can set breakpoints.
38
55
39
-
##Pull request
56
+
### Running Acceptance Tests
40
57
41
-
Format the code before pushing:
42
-
```bash
43
-
make fmt
44
-
```
58
+
Acceptance tests spin up Elasticsearch, Kibana, and Fleet with Docker and run tests in a Go container.
45
59
46
-
Check if the linting:
47
60
```bash
48
-
make lint
49
-
```
61
+
# Start Elasticsearch, Kibana, and Fleet
62
+
make docker-fleet
50
63
51
-
Create a PR and check acceptance test matrix is green.
64
+
# Run all tests
65
+
make testacc
52
66
53
-
## Run provider with local terraform
67
+
# Run a specific test
68
+
make testacc TESTARGS='-run ^TestAccResourceDataStreamLifecycle$$'
54
69
55
-
TBD
70
+
# Cleanup created docker containers
71
+
make docker-clean
72
+
```
56
73
57
-
## Releasing
74
+
### Working with Generated API Clients
75
+
76
+
If your work involves the Kibana API, the API client can be generated directly from the Kibana OpenAPI specs:
77
+
- For Kibana APIs, use the generated client in `generated/kbapi`.
78
+
- To add new endpoints, see [generated/kbapi/README.md](generated/kbapi/README.md).
79
+
- Regenerate clients with:
80
+
```sh
81
+
make transform generate
82
+
```
83
+
84
+
The codebase includes a number of deprecated clients which should not be used anymore:
85
+
-`libs/go-kibana-rest`: Fork of an external library, which is not maintained anymore.
86
+
-`generated/alerting`, `generated/connectors`, `generated/slo`: Older generated clients, but based on non-standard specs. If any of these APIs are needed, they should be included in the `kbapi` client.
87
+
88
+
### Updating Documentation
89
+
90
+
Docs are generated from templates in `templates/` and examples in `examples/`.
91
+
* Update or add templates and examples.
92
+
* Run `make docs-generate` to produce files under `docs/`.
93
+
* Commit the generated files. `make lint` will fail if docs are stale.
94
+
95
+
## Project Structure
96
+
97
+
A quick overview over what's in each folder:
98
+
99
+
*`docs/` - Documentation files
100
+
*`data-sources/` - Documentation for Terraform data sources
101
+
*`guides/` - User guides and tutorials
102
+
*`resources/` - Documentation for Terraform resources
103
+
*`examples/` - Example Terraform configurations
104
+
*`cloud/` - Examples using the cloud to launch testing stacks
105
+
*`data-sources/` - Data source usage examples
106
+
*`resources/` - Resource usage examples
107
+
*`provider/` - Provider configuration examples
108
+
*`generated/` - Auto-generated clients from the `generate-clients` make target
109
+
*`kbapi/` - Kibana API client
110
+
*`alerting/` - (Deprecated) Kibana alerting API client
111
+
*`connectors/` - (Deprecated) Kibana connectors API client
112
+
*`slo/` - (Deprecated) SLO (Service Level Objective) API client
113
+
*`internal/` - Internal Go packages
114
+
*`acctest/` - Acceptance test utilities
115
+
*`clients/` - API client implementations
116
+
*`elasticsearch/` - Elasticsearch-specific logic
117
+
*`fleet/` - Fleet management functionality
118
+
*`kibana/` - Kibana-specific logic
119
+
*`models/` - Data models and structures
120
+
*`schema/` - Connection schema definitions for plugin framework
121
+
*`utils/` - Utility functions
122
+
*`versionutils/` - Version handling utilities
123
+
*`libs/` - External libraries
124
+
*`go-kibana-rest/` - (Deprecated) Kibana REST API client library
* Once the PR is merged, the release CI pipeline can be started by pushing a new release tag to the `main` branch.
144
+
* Once the PR is merged, the release CI pipeline can be started by pushing a new release tag to the `main` branch. (`git tag v0.11.13 && git push origin v0.11.13`)
Copy file name to clipboardExpand all lines: README.md
+1-56Lines changed: 1 addition & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,64 +76,9 @@ provider "elasticstack" {
76
76
}
77
77
```
78
78
79
-
80
79
## Developing the Provider
81
80
82
-
If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements)).
83
-
84
-
To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
85
-
86
-
To install the provider locally into the `~/.terraform.d/plugins/...` directory one can use `make install` command. This will allow to refer this provider directly in the Terraform configuration without needing to download it from the registry.
87
-
88
-
To generate or update documentation, run `make gen`. All the generated docs will have to be committed to the repository as well.
89
-
90
-
In order to run the full suite of Acceptance tests, run `make testacc`.
91
-
92
-
If you have [Docker](https://docs.docker.com/get-docker/) installed, you can use following command to start the Elasticsearch container and run Acceptance tests against it:
93
-
94
-
```sh
95
-
$ make docker-testacc
96
-
```
97
-
98
-
To clean up the used containers and to free up the assigned container names, run `make docker-clean`.
99
-
100
-
Note: there have been some issues encountered when using `tfenv` for local development. It's recommended you move your version management for terraform to `asdf` instead.
0 commit comments