Skip to content

Commit 7907986

Browse files
mdelapenyamdelapenya
authored
chore(gcloud): deprecate old gcp containers, creating subpackages for them (#3063)
* chore: migrate BigQuery to its own package * chore: migrate BigTable to its own package * chore: migrate Datastore to its own package * chore: migrate Firestore to its own package * chore: migrate Pubsub to its own package * chore: migrate Spanner to its own package * chore: use shared options * docs: fix relateive path to include * chore: fix deprecation chain
1 parent 675acc3 commit 7907986

38 files changed

Lines changed: 1512 additions & 262 deletions

‎docs/modules/gcloud-shared.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{% include "../features/common_functional_options.md" %}
2+
3+
#### WithProjectID
4+
5+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
6+
7+
The `WithProjectID` function sets the project ID for the Google Cloud container.

‎docs/modules/gcloud.md‎

Lines changed: 177 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -16,99 +16,221 @@ go get github.com/testcontainers/testcontainers-go/modules/gcloud
1616

1717
## Usage example
1818

19+
The Google Cloud module exposes the following Go packages:
20+
21+
- [BigQuery](#bigquery): `github.com/testcontainers/testcontainers-go/modules/gcloud/bigquery`.
22+
- [BigTable](#bigtable): `github.com/testcontainers/testcontainers-go/modules/gcloud/bigtable`.
23+
- [Datastore](#datastore): `github.com/testcontainers/testcontainers-go/modules/gcloud/datastore`.
24+
- [Firestore](#firestore): `github.com/testcontainers/testcontainers-go/modules/gcloud/firestore`.
25+
- [Pubsub](#pubsub): `github.com/testcontainers/testcontainers-go/modules/gcloud/pubsub`.
26+
- [Spanner](#spanner): `github.com/testcontainers/testcontainers-go/modules/gcloud/spanner`.
1927
!!!info
2028
By default, the all the emulators use `gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators` as the default Docker image, except for the BigQuery emulator, which uses `ghcr.io/goccy/bigquery-emulator:0.6.1`, and Spanner, which uses `gcr.io/cloud-spanner-emulator/emulator:1.4.0`.
2129

22-
### BigQuery
30+
## BigQuery
2331

24-
<!--codeinclude-->
25-
[Creating a BigQuery container](../../modules/gcloud/bigquery_test.go) inside_block:runBigQueryContainer
26-
[Obtaining a BigQuery client](../../modules/gcloud/bigquery_test.go) inside_block:bigQueryClient
27-
<!--/codeinclude-->
32+
### Run function
2833

29-
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the client example above.
34+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
35+
36+
The BigQuery module exposes one entrypoint function to create the BigQuery container, and this function receives three parameters:
37+
38+
```golang
39+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
40+
```
41+
42+
- `context.Context`, the Go context.
43+
- `string`, the Docker image to use.
44+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
45+
46+
### Container Options
47+
48+
When starting the BigQuery container, you can pass options in a variadic way to configure it.
49+
50+
#### Image
51+
52+
Use the second argument in the `Run` function to set a valid Docker image.
53+
In example: `Run(context.Background(), "ghcr.io/goccy/bigquery-emulator:0.6.1")`.
54+
55+
{% include "./gcloud-shared.md" %}
3056

3157
#### Data YAML (Seed File)
3258

33-
- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>
59+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
3460

3561
If you would like to do additional initialization in the BigQuery container, add a `data.yaml` file represented by an `io.Reader` to the container request with the `WithDataYAML` function.
3662
That file is copied after the container is created but before it's started. The startup command then used will look like `--project test --data-from-yaml /testcontainers-data.yaml`.
3763
3864
An example of a `data.yaml` file that seeds the BigQuery instance with datasets and tables is shown below:
3965
4066
<!--codeinclude-->
41-
[Data Yaml content](../../modules/gcloud/testdata/data.yaml)
67+
[Data Yaml content](../../modules/gcloud/bigquery/testdata/data.yaml)
4268
<!--/codeinclude-->
4369
44-
!!!warning
45-
This feature is only available for the `BigQuery` container, and if you pass multiple `WithDataYAML` options, an error is returned.
70+
### Examples
71+
72+
<!--codeinclude-->
73+
[Creating a BigQuery container](../../modules/gcloud/bigquery/examples_test.go) inside_block:runBigQueryContainer
74+
[Obtaining a BigQuery client](../../modules/gcloud/bigquery/examples_test.go) inside_block:bigQueryClient
75+
<!--/codeinclude-->
76+
77+
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the client example above.
78+
79+
## BigTable
80+
81+
### Run function
82+
83+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
84+
85+
The BigTable module exposes one entrypoint function to create the BigTable container, and this function receives three parameters:
86+
87+
```golang
88+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
89+
```
90+
91+
- `context.Context`, the Go context.
92+
- `string`, the Docker image to use.
93+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
94+
95+
### Container Options
96+
97+
When starting the BigTable container, you can pass options in a variadic way to configure it.
98+
99+
#### Image
46100
47-
### BigTable
101+
Use the second argument in the `Run` function to set a valid Docker image.
102+
In example: `Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
103+
104+
{% include "./gcloud-shared.md" %}
105+
106+
### Examples
48107
49108
<!--codeinclude-->
50-
[Creating a BigTable container](../../modules/gcloud/bigtable_test.go) inside_block:runBigTableContainer
51-
[Obtaining a BigTable Admin client](../../modules/gcloud/bigtable_test.go) inside_block:bigTableAdminClient
52-
[Obtaining a BigTable client](../../modules/gcloud/bigtable_test.go) inside_block:bigTableClient
109+
[Creating a BigTable container](../../modules/gcloud/bigtable/examples_test.go) inside_block:runBigTableContainer
110+
[Obtaining a BigTable Admin client](../../modules/gcloud/bigtable/examples_test.go) inside_block:bigTableAdminClient
111+
[Obtaining a BigTable client](../../modules/gcloud/bigtable/examples_test.go) inside_block:bigTableClient
53112
<!--/codeinclude-->
54113
55114
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the Admin client example above.
56115
57-
### Datastore
116+
## Datastore
117+
118+
### Run function
119+
120+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
121+
122+
The Datastore module exposes one entrypoint function to create the Datastore container, and this function receives three parameters:
123+
124+
```golang
125+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
126+
```
127+
128+
- `context.Context`, the Go context.
129+
- `string`, the Docker image to use.
130+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
131+
132+
### Container Options
133+
134+
When starting the Datastore container, you can pass options in a variadic way to configure it.
135+
136+
#### Image
137+
138+
Use the second argument in the `Run` function to set a valid Docker image.
139+
In example: `Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
140+
141+
{% include "./gcloud-shared.md" %}
142+
143+
### Examples
58144
59145
<!--codeinclude-->
60-
[Creating a Datastore container](../../modules/gcloud/datastore_test.go) inside_block:runDatastoreContainer
61-
[Obtaining a Datastore client](../../modules/gcloud/datastore_test.go) inside_block:datastoreClient
146+
[Creating a Datastore container](../../modules/gcloud/datastore/examples_test.go) inside_block:runDatastoreContainer
147+
[Obtaining a Datastore client](../../modules/gcloud/datastore/examples_test.go) inside_block:datastoreClient
62148
<!--/codeinclude-->
63149
64150
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the client example above.
65151
66-
### Firestore
152+
## Firestore
67153
68-
<!--codeinclude-->
69-
[Creating a Firestore container](../../modules/gcloud/firestore_test.go) inside_block:runFirestoreContainer
70-
[Obtaining a Firestore client](../../modules/gcloud/firestore_test.go) inside_block:firestoreClient
71-
<!--/codeinclude-->
154+
### Run function
72155
73-
It's important to set the target string of the `grpc.NewClient` method using the container's URI, as shown in the client example above.
156+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
157+
158+
The Firestore module exposes one entrypoint function to create the Firestore container, and this function receives three parameters:
159+
160+
```golang
161+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
162+
```
163+
164+
- `context.Context`, the Go context.
165+
- `string`, the Docker image to use.
166+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
167+
168+
### Container Options
169+
170+
When starting the Firestore container, you can pass options in a variadic way to configure it.
171+
172+
#### Image
173+
174+
Use the second argument in the `Run` function to set a valid Docker image.
175+
In example: `Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
176+
177+
{% include "./gcloud-shared.md" %}
74178
75-
### Pubsub
179+
### Examples
76180
77181
<!--codeinclude-->
78-
[Creating a Pubsub container](../../modules/gcloud/pubsub_test.go) inside_block:runPubsubContainer
79-
[Obtaining a Pubsub client](../../modules/gcloud/pubsub_test.go) inside_block:pubsubClient
182+
[Creating a Firestore container](../../modules/gcloud/firestore/examples_test.go) inside_block:runFirestoreContainer
183+
[Obtaining a Firestore client](../../modules/gcloud/firestore/examples_test.go) inside_block:firestoreClient
80184
<!--/codeinclude-->
81185
82186
It's important to set the target string of the `grpc.NewClient` method using the container's URI, as shown in the client example above.
83187
84-
### Spanner
188+
## Pubsub
189+
190+
### Run function
191+
192+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
193+
194+
The Pubsub module exposes one entrypoint function to create the Pubsub container, and this function receives three parameters:
195+
196+
```golang
197+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
198+
```
199+
200+
- `context.Context`, the Go context.
201+
- `string`, the Docker image to use.
202+
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
203+
204+
### Container Options
205+
206+
When starting the Pubsub container, you can pass options in a variadic way to configure it.
207+
208+
#### Image
209+
210+
Use the second argument in the `Run` function to set a valid Docker image.
211+
In example: `Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
212+
213+
{% include "./gcloud-shared.md" %}
214+
215+
### Examples
85216
86217
<!--codeinclude-->
87-
[Creating a Spanner container](../../modules/gcloud/spanner_test.go) inside_block:runSpannerContainer
88-
[Obtaining a Spanner Admin client](../../modules/gcloud/spanner_test.go) inside_block:spannerAdminClient
89-
[Obtaining a Spanner Database Admin client](../../modules/gcloud/spanner_test.go) inside_block:spannerDBAdminClient
218+
[Creating a Pubsub container](../../modules/gcloud/pubsub/examples_test.go) inside_block:runPubsubContainer
219+
[Obtaining a Pubsub client](../../modules/gcloud/pubsub/examples_test.go) inside_block:pubsubClient
90220
<!--/codeinclude-->
91221
92-
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the Admin client example above.
222+
It's important to set the target string of the `grpc.NewClient` method using the container's URI, as shown in the client example above.
93223
94-
## Module Reference
224+
## Spanner
95225
96226
### Run function
97227
98-
- Since testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>
228+
- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
99229
100-
!!!info
101-
The `RunXXXContainer(ctx, opts...)` functions are deprecated and will be removed in the next major release of _Testcontainers for Go_.
102-
103-
The GCloud module exposes one entrypoint function to create the different GCloud emulators, and each function receives three parameters:
230+
The Spanner module exposes one entrypoint function to create the Spanner container, and this function receives three parameters:
104231
105232
```golang
106-
func RunBigQuery(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*BigQueryContainer, error)
107-
func RunBigTable(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*BigTableContainer, error)
108-
func RunDatastore(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*DatastoreContainer, error)
109-
func RunFirestore(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*FirestoreContainer, error)
110-
func RunPubsub(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*PubsubContainer, error)
111-
func RunSpanner(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*SpannerContainer, error)
233+
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
112234
```
113235
114236
- `context.Context`, the Go context.
@@ -117,15 +239,21 @@ func RunSpanner(ctx context.Context, img string, opts ...testcontainers.Containe
117239
118240
### Container Options
119241
120-
When starting any of the GCloud containers, you can pass options in a variadic way to configure it.
242+
When starting the Spanner container, you can pass options in a variadic way to configure it.
121243
122244
#### Image
123245
124-
Use the second argument in the `RunXXX` function (`RunBigQuery, RunDatastore`, ...) to set a valid Docker image.
125-
In example: `RunXXX(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
246+
Use the second argument in the `Run` function to set a valid Docker image.
247+
In example: `Run(context.Background(), "gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators")`.
248+
249+
{% include "./gcloud-shared.md" %}
126250
127-
{% include "../features/common_functional_options.md" %}
251+
### Examples
128252
129-
### Container Methods
253+
<!--codeinclude-->
254+
[Creating a Spanner container](../../modules/gcloud/spanner/examples_test.go) inside_block:runSpannerContainer
255+
[Obtaining a Spanner Admin client](../../modules/gcloud/spanner/examples_test.go) inside_block:spannerAdminClient
256+
[Obtaining a Spanner Database Admin client](../../modules/gcloud/spanner/examples_test.go) inside_block:spannerDBAdminClient
257+
<!--/codeinclude-->
130258
131-
The GCloud container exposes the following methods:
259+
It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the Admin client example above.

‎modules/gcloud/bigquery.go‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,15 @@ import (
88
"github.com/testcontainers/testcontainers-go/wait"
99
)
1010

11-
// Deprecated: use RunBigQuery instead
11+
// Deprecated: use [bigquery.Run] instead.
1212
// RunBigQueryContainer creates an instance of the GCloud container type for BigQuery.
1313
func RunBigQueryContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*GCloudContainer, error) {
1414
return RunBigQuery(ctx, "ghcr.io/goccy/bigquery-emulator:0.6.1", opts...)
1515
}
1616

17+
// Deprecated: use [bigquery.Run] instead.
1718
// RunBigQuery creates an instance of the GCloud container type for BigQuery.
18-
// The URI will always use http:// as the protocol.
19+
// The URI uses http:// as the protocol.
1920
func RunBigQuery(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*GCloudContainer, error) {
2021
req := testcontainers.GenericContainerRequest{
2122
ContainerRequest: testcontainers.ContainerRequest{

0 commit comments

Comments
 (0)