Skip to content

Commit ca7428d

Browse files
staceysalamon-aivenstaceysalamon-aiven
authored
update: fork a service with terraform (#1012)
1 parent c332178 commit ca7428d

File tree

3 files changed

+115
-80
lines changed

3 files changed

+115
-80
lines changed

‎docs/platform/concepts/rename-services.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Rename a service
3+
---
4+
5+
You cannot rename a service after creation. Instead, you can create a fork
6+
with the new name and delete the original service.
7+
8+
1. Stop writes on the the service.
9+
1. [Fork the service](/docs/platform/concepts/service-forking).
10+
1. Point your clients to the new service and add any integrations or SSO configuration
11+
that weren't copied.
12+
1. Test the forked service.
13+
1. [Delete the original service](/docs/platform/concepts/service-power-cycle).

‎docs/platform/concepts/service-forking.md‎

Lines changed: 101 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,25 @@
11
---
2-
title: Service forking
2+
title: Fork a service
33
---
44

55
import Tabs from '@theme/Tabs';
66
import TabItem from '@theme/TabItem';
77
import RelatedPages from "@site/src/components/RelatedPages";
8-
import ConsoleLabel from "@site/src/components/ConsoleIcons"
8+
import ConsoleLabel from "@site/src/components/ConsoleIcons";
9+
import TerraformSample from '@site/src/components/CodeSamples/TerraformSample';
910

10-
[Fork your Aiven service](/docs/platform/concepts/service-forking) to make a copy of the service, for example to create a snapshot to analyze an issue.
11+
Fork an Aiven service to create a complete and independent copy of it from its latest backup.
1112

12-
Other typical use cases include creating a development copy of your production
13-
environment, upgrade testing, or creating an instance in a different
14-
cloud/geographical location/under a different plan.
13+
For services with Point in Time Recovery (PITR), you can choose to fork from the latest
14+
transaction or from a specific point in time. Forked services are independent
15+
and don't share resources with or increase the load on the original service.
16+
Common use cases for forking include:
1517

16-
When you fork a service, the following items are copied into the new
17-
service:
18-
19-
- Configurations
20-
- Databases
21-
- Service users
22-
- Connection pools
23-
24-
Forks are independent and do not increase the load on the original service. The data is
25-
restored from the latest backup stored separately from the service.
26-
27-
:::important
28-
29-
- Service integrations are not copied over to the forked version, and need to be
30-
re-established for each new copy.
31-
- You cannot [fork Aiven for ClickHouse®](/docs/products/clickhouse/howto/restore-backup)
32-
or Aiven for Apache Cassandra® services to a lower amount of nodes.
33-
34-
:::
18+
- Creating a snapshot to analyze an issue.
19+
- Creating a development copy of your production environment.
20+
- Testing upgrades before applying them to production services.
21+
- Creating an instance in a different cloud provider, region, or with a different plan.
22+
- [Renaming a service](/docs/platform/concepts/rename-services).
3523

3624
You can fork the following Aiven services:
3725

@@ -42,102 +30,135 @@ You can fork the following Aiven services:
4230
- M3DB
4331
- MySQL
4432
- OpenSearch®
45-
46-
:::important
47-
When you fork an Aiven for OpenSearch® service, any Single Sign-On
48-
(SSO) methods configured at the service level, such as SAML, must be
49-
explicitly reconfigured for the forked service. SSO configurations
50-
are linked to specific URLs and endpoints, which change during
51-
forking. Failing to reconfigure SSO methods for the forked service
52-
can lead to authentication problems and potentially disrupt user
53-
access.
54-
:::
55-
5633
- PostgreSQL®
5734

58-
## Fork a service
35+
When you fork a service, the service configurations, databases, service users,
36+
and connection pools are copied to the new service.
5937

60-
When forking a service with Point in Time Recovery (PITR), you can
61-
choose to fork from the latest transaction or select a specific point in
62-
the past to fork from.
63-
Fork your Aiven service to make a copy of the service.
38+
## Limitations
6439

65-
:::important
66-
You can only fork services that have at least one [backup](/docs/platform/concepts/service_backups).
67-
:::
40+
- You can only fork services that have at least one
41+
[backup](/docs/platform/concepts/service_backups).
42+
- Service integrations are not copied over to the forked versions.
43+
- You cannot [fork Aiven for ClickHouse®](/docs/products/clickhouse/howto/restore-backup)
44+
or Aiven for Apache Cassandra® services to a lower amount of nodes.
45+
- Single sign-on (SSO) methods are not copied over to forked Aiven for OpenSearch® services
46+
because they are linked to specific URLs and endpoints, which change during
47+
forking. If you don't configure the SSO methods for the forked service, this can
48+
disrupt user access.
49+
50+
## Fork a service
6851

6952
<Tabs groupId="group1">
7053
<TabItem value="Console" label="Console" default>
7154
1. Log in to [Aiven Console](https://console.aiven.io/).
7255
1. In your project, click <ConsoleLabel name="services"/> and click the service to fork.
7356
1. Click <ConsoleLabel name="Backups"/> and click **Fork & restore**.
74-
1. In the **New Database Fork** window, set the details for the new service.
75-
1. Click **Create fork**.
76-
77-
Apply any integrations required by the fork.
57+
1. Configure the new service and click **Create fork**.
7858

7959
</TabItem>
8060
<TabItem value="CLI" label="CLI">
8161

82-
1. Prepare the command to create service, this will contain the
83-
new copy of your data store.
84-
1. Add the `service_to_fork_from` parameter to specify the service to
85-
use as the source. Change service type accordingly with `-t`, run
86-
the following command to see available options:
62+
Use the
63+
[create service command](https://aiven.io/docs/tools/cli/service-cli#avn-cli-service-create)
64+
with the `service_to_fork_from` parameter to specify the service to use as the source.
8765

88-
```bash
89-
avn service types
90-
```
91-
92-
For example, to create a fork of your `forker` PostgreSQL®
93-
service, and name it `forked`, the command would be something like:
66+
The following example creates a fork of a PostgreSQL® service named `source-pg`
67+
and names it `pg-fork`.
9468

9569
```bash
96-
avn service create forked --project PROJECT_NAME --cloud CLOUD_NAME -t pg --plan business-4 -c service_to_fork_from=forker
70+
avn service create pg-fork \
71+
--plan business-4 \
72+
--project example-project \
73+
--service-type pg \
74+
--cloud google-europe-west1 \
75+
--service-to-fork-from source-pg
9776
```
9877

99-
Apply any integrations required by the fork.
78+
To specify the backup to fork from, add the `--recovery-target-time` parameter
79+
and set it to a time between the first and latest available backups. The following
80+
example creates a fork by specifying the backup:
81+
82+
```bash
83+
avn service create pg-fork \
84+
--plan business-4 \
85+
--project example-project \
86+
--service-type pg \
87+
--cloud google-europe-west1 \
88+
--service-to-fork-from source-pg \
89+
--recovery-target-time "2025-07-01T15:16:22+00:00"
90+
```
10091

10192
</TabItem>
10293
<TabItem value="API" label="API">
10394

104-
Use the [`ServiceCreate` endpoint](https://api.aiven.io/doc/#tag/Service/operation/ServiceCreate)
105-
and set the `service_to_fork_from` and `project_to_fork_from` parameters to specify the
106-
source service in the `user_config` property.
95+
Use the
96+
[`ServiceCreate` endpoint](https://api.aiven.io/doc/#tag/Service/operation/ServiceCreate)
97+
and set the `service_to_fork_from` parameter in the `user_config` property
98+
to the source service.
10799

108-
For example:
100+
The following example creates a fork of a PostgreSQL service from the latest backup
101+
of the service `source-pg-service`:
109102

110-
```bash {11,12}
111-
curl --location 'https://console.aiven.io/v1/project/dest-project/service' \
103+
```bash
104+
curl --location 'https://console.aiven.io/v1/project/example-project/service' \
112105
--header 'Content-Type: application/json' \
113106
--header 'Authorization: token' \
114107
--data '{
115108
"cloud":"google-europe-central2",
116-
"group_name":"default",
117109
"plan":"business-4",
118-
"service_name":"dest-name",
110+
"service_name":"pg-fork",
119111
"service_type":"pg",
120112
"user_config":{
121-
"service_to_fork_from":"source-service",
122-
"project_to_fork_from":"source-project",
123-
"pg_version":"16"
113+
"service_to_fork_from":"source-pg-service",
124114
}
125115
}'
126116
```
127117

128-
Apply any integrations required by the fork.
118+
To specify the backup to fork from, set the `recovery_target_time`
119+
to a time between the first and latest available backups.
120+
121+
The following example forks a PostgreSQL service from a backup
122+
taken at a specific point in time:
123+
124+
```bash
125+
curl --location 'https://console.aiven.io/v1/project/example-project/service' \
126+
--header 'Content-Type: application/json' \
127+
--header 'Authorization: token' \
128+
--data '{
129+
"cloud":"google-europe-central2",
130+
"plan":"business-4",
131+
"service_name":"pg-fork",
132+
"service_type":"pg",
133+
"user_config":{
134+
"service_to_fork_from":"source-pg-service",
135+
"recovery_target_time": "2024-06-01T12:00:00+00:00",
136+
}
137+
}'
138+
```
129139

130140
</TabItem>
131-
</Tabs>
141+
<TabItem value="terraform" label="Terraform">
142+
143+
Use the `service_to_fork_from` attribute in the user config of your service resource.
132144

133-
## Rename a service
145+
The following example creates a fork of a PostgreSQL service. The source service is
146+
in the Google Cloud `europe-west1` region and the fork is in the AWS `eu-central-1` region.
134147

135-
A service cannot be renamed after creation. Instead, use a fork:
148+
<TerraformSample filename='postgres/postgres_fork/service.tf' />
149+
150+
To specify the backup to fork from, set the `recovery_target_time` attribute
151+
to a time between the first and latest available backups.
152+
153+
More information on the service resources and their configuration options
154+
are available in the
155+
[Terraform documentation](https://registry.terraform.io/providers/aiven/aiven/latest/docs).
156+
157+
</TabItem>
158+
</Tabs>
136159

137-
1. Stop service writes on the service to rename.
138-
1. Fork the service under a different name.
139-
1. Point clients to the new service.
140-
1. Delete the original service when you are ready.
160+
During the forking process, the fork might initially have only one node while backups
161+
are being taken. The other nodes appear after the backup process is complete.
141162

142163
<RelatedPages/>
143164

‎sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ const sidebars: SidebarsConfig = {
225225
},
226226
'platform/howto/create_new_service',
227227
'platform/concepts/service-power-cycle',
228+
'platform/concepts/rename-services',
228229
'platform/howto/tag-resources',
229230
'platform/howto/search-services',
230231
'platform/howto/create_new_service_user',

0 commit comments

Comments
 (0)