From 7d1eb14054d46ef53a2c34c8d1143eca82371a14 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 23 Jun 2023 16:14:42 +0200 Subject: [PATCH 01/36] feat(terraform): create initial draft in configuration management --- .../index.adoc} | 2 +- .../configuration-management /terraform.adoc | 149 ++++++++++++++++++ 2 files changed, 150 insertions(+), 1 deletion(-) rename site/docs/v1/tech/admin-guide/{configuration-management.adoc => configuration-management /index.adoc} (99%) create mode 100644 site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc diff --git a/site/docs/v1/tech/admin-guide/configuration-management.adoc b/site/docs/v1/tech/admin-guide/configuration-management /index.adoc similarity index 99% rename from site/docs/v1/tech/admin-guide/configuration-management.adoc rename to site/docs/v1/tech/admin-guide/configuration-management /index.adoc index 9f8720afb9..f835039b0f 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management /index.adoc @@ -38,7 +38,7 @@ Using this approach gives you full access to the FusionAuth API. === Terraform -There is a community supported, open source terraform provider which allows you to manage FusionAuth using Terraform, an open source infrastructure tool. +There is a community supported, open source terraform provider which allows you to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. Here is the https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform provider documentation]. diff --git a/site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc new file mode 100644 index 0000000000..d0c996dabe --- /dev/null +++ b/site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc @@ -0,0 +1,149 @@ +--- +layout: doc +title: Terraform +description: Manage FusionAuth configuration changes over time with Terraform. +navcategory: admin +prerequisites: FusionAuth +technology: Terraform +--- + +== Overview + +In this section we dig deeper in the the community supported, open source https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform provider] with which you will be able to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. + +* <> +* <> +** <> +** <> +* <> +** <> +* <> +* <> +* <> + +== Prerequisites + +{% include docs/integration/_prerequisites.md %} + +== Initial Setup + +ipsum + +=== FusionAuth API Key + +https://fusionauth.io/docs/v1/tech/apis/api-keys + +http://fusionauth-terraform:9011/admin/api-key/ +- Copy key (e.g. yqT4LSMCWDYgwbPBA_AxmXHm7_qNFT9jbOi3wL9Jr65ymNkNnFisAvjY) +- Do Not select any endpoint methods to create a super user key. A super user API Key has access to all API endpoints. +- Save + +=== Initializing Terraform Working Directory + +[source] +---- +mkdir your.fusionauth.domain +---- + +[source] +---- +cd your.fusionauth.domain +---- + +go to https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs +Click USE PROVIDER +Copy Information +create `main.tf` +Add the previously created key as api_key and host as configuration options. +Make sure host is a URL including protocol + +[source] +---- +terraform { + required_providers { + fusionauth = { + source = "gpsinsight/fusionauth" + version = "0.1.90" + } + } +} + +provider "fusionauth" { + api_key = "yqT4LSMCWDYgwbPBA_AxmXHm7_qNFT9jbOi3wL9Jr65ymNkNnFisAvjY" + host = "https://your.fusionauth.domain" +} +---- + +== Terraform Import + +If you have existing resources you want to manage via terraform you can import the current configuration via terraform import. +(Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) + +- User +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user + +- Tenant +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant +why importing default tenant is good practice, to manage fusionauth application related topics it is always in the default tenant, there is not necessarily a need to create a different tenant as you create multiple applications: https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant + +- Application +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application + +=== Terraform Data Source Instead Of Import + +Instead of importing a ressource you can use existing configuration as a Data Source + +- Tenant +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/tenant + +- Application +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/application + +== Terraform Create + +To create a new resource you can go through the list of ressources available to you in the provider https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs and pick the ressource you are interested in. + +Each resource contains information about required and opitional arguments. + +- Application +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application + +- Application Role +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role + +- User +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user + +- Registration +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration + +== Terraform Update + +- Tenant +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant + +- Application +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application + +- Application Role +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role + +- User +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user + +- Registration +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration + +== Terraform Remove + +- Application +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application + +- Application Role +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role + +- Registration +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration + +- User +https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user From a96dbba0a14581d1a111fd75e54ea2b75156cd9c Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 10:20:59 +0200 Subject: [PATCH 02/36] refactor(configuration-management): Create sub-menu structure with Terraform --- site/_layouts/doc.liquid | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/site/_layouts/doc.liquid b/site/_layouts/doc.liquid index 89e895d4d2..80846d3305 100644 --- a/site/_layouts/doc.liquid +++ b/site/_layouts/doc.liquid @@ -141,8 +141,14 @@ Admin Guide
  • Overview
    • -
  • Account Portal
    • -
  • Config Management
    • +
  • Account Portal
    • +
  • + Config Management + +
  • Editions and Features
  • Key Rotation
  • Licensing
    • From 98c6f1f2c9efcc825e6e62f67a0973bc334f204d Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 10:44:53 +0200 Subject: [PATCH 03/36] fix(configuration-management): Remove space from folder name --- .../index.adoc | 0 .../terraform.adoc | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename site/docs/v1/tech/admin-guide/{configuration-management => configuration-management}/index.adoc (100%) rename site/docs/v1/tech/admin-guide/{configuration-management => configuration-management}/terraform.adoc (100%) diff --git a/site/docs/v1/tech/admin-guide/configuration-management /index.adoc b/site/docs/v1/tech/admin-guide/configuration-management/index.adoc similarity index 100% rename from site/docs/v1/tech/admin-guide/configuration-management /index.adoc rename to site/docs/v1/tech/admin-guide/configuration-management/index.adoc diff --git a/site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc similarity index 100% rename from site/docs/v1/tech/admin-guide/configuration-management /terraform.adoc rename to site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc From b1a19376fb731c52c9f5eea733a7486cac710f15 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 16:00:22 +0200 Subject: [PATCH 04/36] refactor(terraform): Update draft content --- .../configuration-management/terraform.adoc | 182 +++++++++++++----- 1 file changed, 130 insertions(+), 52 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index d0c996dabe..0840bcce81 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -9,13 +9,15 @@ technology: Terraform == Overview -In this section we dig deeper in the the community supported, open source https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform provider] with which you will be able to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. +In this section we dig deeper in the the community supported, open source link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform Provider] with which you will be able to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. * <> * <> ** <> ** <> * <> +** <> +** <> ** <> * <> * <> @@ -23,23 +25,25 @@ In this section we dig deeper in the the community supported, open source https: == Prerequisites -{% include docs/integration/_prerequisites.md %} +In order for you to get the most value from this guide, you should have a FusionAuth instance set up for a user to log in with. + +If you don't have this set up yet, please review the following link: + +* link:/docs/v1/tech/5-minute-setup-guide[5 minute setup guide] - get a FusionAuth instance up and running with a simple application == Initial Setup -ipsum +In the initial setup we go through the initializing of the Terraform working directory with the FusionAuth API key. === FusionAuth API Key -https://fusionauth.io/docs/v1/tech/apis/api-keys - -http://fusionauth-terraform:9011/admin/api-key/ -- Copy key (e.g. yqT4LSMCWDYgwbPBA_AxmXHm7_qNFT9jbOi3wL9Jr65ymNkNnFisAvjY) -- Do Not select any endpoint methods to create a super user key. A super user API Key has access to all API endpoints. -- Save +Create an unlimited super user API Key as described in link:/docs/v1/tech/apis/authentication#managing-api-keys[Managing API Keys] by not selecting any endpoint methods to create a super user key. A super user API Key has access to all API endpoints. Copy the key before pressing the Save button. +//TODO: screenshot http://fusionauth-terraform:9011/admin/api-key/ === Initializing Terraform Working Directory +With the copied API Key from your fusionauth environment we initialize the Terraform working directory. By creating a new directory. + [source] ---- mkdir your.fusionauth.domain @@ -50,12 +54,13 @@ mkdir your.fusionauth.domain cd your.fusionauth.domain ---- -go to https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs -Click USE PROVIDER -Copy Information -create `main.tf` -Add the previously created key as api_key and host as configuration options. -Make sure host is a URL including protocol +And add the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform Provider] configuration in the directory by: + +* Open the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] +* Click USE PROVIDER and Copy Information +* Create the `main.tf` Terraform configuration with the copied information +* Add the previously created key as api_key and add the host as configuration options +* Make sure host is the full URL including protocol [source] ---- @@ -63,76 +68,149 @@ terraform { required_providers { fusionauth = { source = "gpsinsight/fusionauth" - version = "0.1.90" + version = "0.1.91" } } } provider "fusionauth" { - api_key = "yqT4LSMCWDYgwbPBA_AxmXHm7_qNFT9jbOi3wL9Jr65ymNkNnFisAvjY" + api_key = "yqTs2LSMd23DYgwbPBA_AxmXHm7_qNFT9jbi3wL9Jr65ymNkNnFisAvjY" host = "https://your.fusionauth.domain" } ---- +Finally, the following command performs several different initialization steps in order to prepare the current working directory for use with Terraform. + +[source] +---- +terraform init +---- + +It is always safe to run link:https://developer.hashicorp.com/terraform/cli/commands/init[init] multiple times, to bring the working directory up to date with changes in the configuration. Though subsequent runs may give errors, this command will never delete your existing configuration or state. + == Terraform Import -If you have existing resources you want to manage via terraform you can import the current configuration via terraform import. -(Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) +Before we go in to Creating, Updating and Removing of resources we first look in to the link:https://developer.hashicorp.com/terraform/language/import[Import] functionality. If you have existing resources you want to manage via terraform you need to import the current configuration via import to be able to manage it via Terraform. +//Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) -- User -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user +=== Importing The Default Tenant +We start by importing the default tenant based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] by adding the following code below. -- Tenant -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant -why importing default tenant is good practice, to manage fusionauth application related topics it is always in the default tenant, there is not necessarily a need to create a different tenant as you create multiple applications: https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant +Why importing default tenant is good practice? Manage FusionAuth application related topics is always part of the default tenant, as well as there is not necessarily a need to create a different tenant as you create multiple applications. +//knowledge source https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant -- Application -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application +[source] +---- +import "fusionauth_tenant" "default" { + name = "Default" +} +---- + +=== Importing The FusionAuth Application +And import the default FusionAuth application based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] by adding the following code. + +[source] +---- +import "fusionauth_application" "FusionAuth" { + tenant_id = fusionauth_tenant.default.id + name = "FusionAuth" +} +---- === Terraform Data Source Instead Of Import -Instead of importing a ressource you can use existing configuration as a Data Source +Instead of importing a ressource you can use existing configuration as a Data Source instead, the list of all supported data sources you can find in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] -- Tenant -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/tenant +If you choose to manage the default Tenant and FusionAuth Application outside instead as shown previously inside the Terraform configuration. But still add Applications in to the default Tenant via Terraform, you can reference it in the configuration as a data source. -- Application -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/application +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/tenant[Terraform Data Source: Application] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/application[Terraform Data Source: Application] + +[source] +---- +data "fusionauth_tenant" "default" { + name = "Default" +} + +data "fusionauth_application" "FusionAuth" { + tenant_id = fusionauth_tenant.default.id + name = "FusionAuth" +} +---- == Terraform Create -To create a new resource you can go through the list of ressources available to you in the provider https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs and pick the ressource you are interested in. +To create a new resource you can go through the list of resources available to you in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] and pick the ressource you are interested in. Each resource contains information about required and optional arguments. -Each resource contains information about required and opitional arguments. +In this example we create an Application called forum in the default Tenant with related Roles (admin and user), Users (forum-user1 and forum-admin1) and according Registrations: -- Application -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role[Terraform Resource: Application Role] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] -- Application Role -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role +[source] +---- +resource "fusionauth_application" "forum" { + tenant_id = fusionauth_tenant.default.id + name = "forum" +} -- User -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user +resource "fusionauth_application_role" "forum_admin_role" { + application_id = fusionauth_application.forum.id + is_default = false + is_super_role = true + name = "admin" +} -- Registration -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration +resource "fusionauth_application_role" "forum_user_role" { + application_id = fusionauth_application.forum.id + is_default = true + is_super_role = false + name = "user" +} -== Terraform Update +resource "fusionauth_user" "forum-user1" { + email = "forum-user1@email.internal" + first_name = "John" + last_name = "Doe" + middle_name = "William" + password_change_required = false + username_status = "ACTIVE" +} -- Tenant -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant +resource "fusionauth_user" "forum-admin1" { + email = "forum-user1@email.internal" + first_name = "John" + last_name = "Doe" + middle_name = "William" + password_change_required = false + username_status = "ACTIVE" +} -- Application -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application +resource "fusionauth_registration" "forum-admin1-admin-role" { + user_id = fusionauth_user.forum-admin1.id + application_id = data.fusionauth_application.forum.id + roles = ["admin"] +} -- Application Role -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role +resource "fusionauth_registration" "forum-user1-user-role" { + user_id = fusionauth_user.forum-user1.id + application_id = data.fusionauth_application.forum.id + roles = ["user"] +} +---- -- User -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user +== Terraform Update + +Once a resource is imported or created you can update it accordingly. + +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role[Terraform Resource: Application Role] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] +* link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] -- Registration -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration == Terraform Remove From 5b019ceb92a3187d525b5fb3ba1803b9a3052c1c Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 17:53:33 +0200 Subject: [PATCH 05/36] refactor(terraform): Update draft import section --- .../configuration-management/terraform.adoc | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index 0840bcce81..0d8ff1c531 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -47,10 +47,6 @@ With the copied API Key from your fusionauth environment we initialize the Terra [source] ---- mkdir your.fusionauth.domain ----- - -[source] ----- cd your.fusionauth.domain ---- @@ -93,27 +89,39 @@ It is always safe to run link:https://developer.hashicorp.com/terraform/cli/comm Before we go in to Creating, Updating and Removing of resources we first look in to the link:https://developer.hashicorp.com/terraform/language/import[Import] functionality. If you have existing resources you want to manage via terraform you need to import the current configuration via import to be able to manage it via Terraform. //Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) +// The import command works and i've tested it, but the import configuration has a issue https://github.com/gpsinsight/terraform-provider-fusionauth/issues/214 === Importing The Default Tenant -We start by importing the default tenant based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] by adding the following code below. +We start by importing the default tenant based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] by adding the following code below to `import.tf`. Why importing default tenant is good practice? Manage FusionAuth application related topics is always part of the default tenant, as well as there is not necessarily a need to create a different tenant as you create multiple applications. //knowledge source https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant +Create an `import.tf` configuration file with the following content: + [source] ---- -import "fusionauth_tenant" "default" { - name = "Default" +import { + to = fusionauth_tenant.default + id = "374eba67-12b0-4957-2a4e-a91a8c6f9bfb" } ---- +And link:https://developer.hashicorp.com/terraform/language/import/generating-configuration[generate] a tenant configuration file from it with the following command which you then can apply: + +[source] +---- +terraform plan -generate-config-out=generated_resources.tf +terraform apply +---- + === Importing The FusionAuth Application -And import the default FusionAuth application based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] by adding the following code. +The same works with importing the default FusionAuth application based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] by adding the following code to `import.tf`. [source] ---- -import "fusionauth_application" "FusionAuth" { - tenant_id = fusionauth_tenant.default.id - name = "FusionAuth" +import { + to = fusionauth_application.FusionAuth + id = "3c219e58-ed0e-4b18-ad48-f4f92793ae32" } ---- @@ -133,7 +141,6 @@ data "fusionauth_tenant" "default" { } data "fusionauth_application" "FusionAuth" { - tenant_id = fusionauth_tenant.default.id name = "FusionAuth" } ---- From f2a46432e951923f4f040c4b0925671cdca59327 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 19:34:04 +0200 Subject: [PATCH 06/36] refactor(terraform): Update draft create section --- .../configuration-management/terraform.adoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index 0d8ff1c531..787252ef83 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -156,10 +156,12 @@ In this example we create an Application called forum in the default Tenant with * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] +For referenced IDs which are Data Sources use a leading `data.` for the specification e.g. `tenant_id = data.fusionauth_tenant.default.id`. + [source] ---- resource "fusionauth_application" "forum" { - tenant_id = fusionauth_tenant.default.id + tenant_id = data.fusionauth_tenant.default.id name = "forum" } @@ -183,6 +185,7 @@ resource "fusionauth_user" "forum-user1" { last_name = "Doe" middle_name = "William" password_change_required = false + password = "%WLTvrsYELsyPqC^R7FMUNxt##VyDf6XaWk2R7!gS$oL76Ww" username_status = "ACTIVE" } @@ -192,22 +195,25 @@ resource "fusionauth_user" "forum-admin1" { last_name = "Doe" middle_name = "William" password_change_required = false + password = "@CfosPAVT3&hCzz5c^F5BxNUY$X!@s!7Wx9bd6Yon54e3" username_status = "ACTIVE" } resource "fusionauth_registration" "forum-admin1-admin-role" { user_id = fusionauth_user.forum-admin1.id - application_id = data.fusionauth_application.forum.id + application_id = fusionauth_application.forum.id roles = ["admin"] } resource "fusionauth_registration" "forum-user1-user-role" { user_id = fusionauth_user.forum-user1.id - application_id = data.fusionauth_application.forum.id + application_id = fusionauth_application.forum.id roles = ["user"] } ---- +Once you are happy with your configuration run `terraform plan` and if you are not experiencing errors and are ok with the planned changes you can go ahead with `terraform apply`. + == Terraform Update Once a resource is imported or created you can update it accordingly. From da6eb8843ab452a7a55077d54914d4a52fd56aa6 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 19:45:34 +0200 Subject: [PATCH 07/36] fix(terraform): user admin email --- .../v1/tech/admin-guide/configuration-management/terraform.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index 787252ef83..f41f698756 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -190,7 +190,7 @@ resource "fusionauth_user" "forum-user1" { } resource "fusionauth_user" "forum-admin1" { - email = "forum-user1@email.internal" + email = "forum-admin1@email.internal" first_name = "John" last_name = "Doe" middle_name = "William" From ff31c6eb8015c0fb728486ba017d7aa0b760ab92 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 20:01:31 +0200 Subject: [PATCH 08/36] refactor(terraform): final draft Update and Remove section --- .../configuration-management/terraform.adoc | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index f41f698756..e635da1fd2 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -216,7 +216,7 @@ Once you are happy with your configuration run `terraform plan` and if you are n == Terraform Update -Once a resource is imported or created you can update it accordingly. +Once a resource is either imported or created you can changing existing attributes accordingly in your existing `.tf` files or add additional ones according to the documentation. * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] @@ -224,17 +224,10 @@ Once a resource is imported or created you can update it accordingly. * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] +If you want to know what already has been defined by terraform but not specified in your `.tf` files you can run `terraform show`. -== Terraform Remove - -- Application -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application +The configuration can get very large and if you want to show only very specific resources you can list all resources with `terraform state list` and show the resource state with `terraform state show ` accordingly. -- Application Role -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role - -- Registration -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration +== Terraform Remove -- User -https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user +If you want to remove a resource you can comment or delete the lines accordingly. Run `terraform plan` and `terraform apply` once modified. From f523739707b4de25172a116a4511f9161e7a63eb Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 30 Jun 2023 20:16:05 +0200 Subject: [PATCH 09/36] refactor(configuration-management): reference to terraform example and move some details in to terraform --- .../v1/tech/admin-guide/configuration-management/index.adoc | 6 +----- .../admin-guide/configuration-management/terraform.adoc | 2 ++ 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/index.adoc b/site/docs/v1/tech/admin-guide/configuration-management/index.adoc index f835039b0f..c343bfc456 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/index.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/index.adoc @@ -40,11 +40,7 @@ Using this approach gives you full access to the FusionAuth API. There is a community supported, open source terraform provider which allows you to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. -Here is the https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform provider documentation]. - -Since it is a community project, it is not as complete as the client libraries. If you find yourself needing to manage something not currently supported, you can contribute to the https://github.com/gpsinsight/terraform-provider-fusionauth[project using GitHub]. - -//TODO example +For more details checkout our link:/docs/v1/tech/admin-guide/configuration-management/terraform[example] === Pulumi diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index e635da1fd2..34ddceb0cb 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -11,6 +11,8 @@ technology: Terraform In this section we dig deeper in the the community supported, open source link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform Provider] with which you will be able to manage FusionAuth using Terraform, an open source infrastructure as code automation tool. +Since it is a community project, it is not as complete as the client libraries. If you find yourself needing to manage something not currently supported, you can contribute to the https://github.com/gpsinsight/terraform-provider-fusionauth[project using GitHub]. + * <> * <> ** <> From 70e011080cb4c0d97db50da0eb56402e76179661 Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 7 Jul 2023 16:08:47 +0200 Subject: [PATCH 10/36] refactor(terraform): update guide with review feedback --- .../configuration-management/terraform.adoc | 168 +++++++++++++++--- 1 file changed, 146 insertions(+), 22 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index 34ddceb0cb..0bd821ab5d 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -27,11 +27,12 @@ Since it is a community project, it is not as complete as the client libraries. == Prerequisites -In order for you to get the most value from this guide, you should have a FusionAuth instance set up for a user to log in with. +In order for you to get the most value from this guide, you should have a FusionAuth instance set up and Terraform CLI ready in your runtime. -If you don't have this set up yet, please review the following link: +If you don't have this set up yet, please review the following links: -* link:/docs/v1/tech/5-minute-setup-guide[5 minute setup guide] - get a FusionAuth instance up and running with a simple application +* link:/docs/v1/tech/5-minute-setup-guide[5 minute setup guide] - get a FusionAuth instance up and running with a simple application. +* To use Terraform CLI you will need to install it. The link:https://developer.hashicorp.com/terraform/tutorials/docker-get-started/install-cli[Install Terraform] part in the link:https://developer.hashicorp.com/terraform/tutorials/docker-get-started[Get Started - Docker] guide from Terraform will explain you how. == Initial Setup @@ -44,12 +45,12 @@ Create an unlimited super user API Key as described in link:/docs/v1/tech/apis/a === Initializing Terraform Working Directory -With the copied API Key from your fusionauth environment we initialize the Terraform working directory. By creating a new directory. +With the copied API Key from your FusionAuth environment we initialize the Terraform working directory. By creating a new directory named after your FusionAuth instance domain name. [source] ---- -mkdir your.fusionauth.domain -cd your.fusionauth.domain +mkdir your.fusionauth.instance +cd your.fusionauth.instance ---- And add the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/[FusionAuth Terraform Provider] configuration in the directory by: @@ -88,50 +89,163 @@ It is always safe to run link:https://developer.hashicorp.com/terraform/cli/comm == Terraform Import -Before we go in to Creating, Updating and Removing of resources we first look in to the link:https://developer.hashicorp.com/terraform/language/import[Import] functionality. If you have existing resources you want to manage via terraform you need to import the current configuration via import to be able to manage it via Terraform. +Before we go in to Creating, Updating and Removing of resources we first look in to the link:https://developer.hashicorp.com/terraform/language/import[Import] functionality. If you have existing resources you want to manage via Terraform you need to import the current configuration to be able to manage it via Terraform. +[NOTE.note] +==== +The cleaner way is to create all resources through Terraform instead, but in certain scenarios you will have to use Import or Data Source and we go through a few examples in this ant the next section. +==== //Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) +// The import and generate config command works and i've tested it, but the import configuration has a issue https://github.com/gpsinsight/terraform-provider-fusionauth/issues/214 -// The import command works and i've tested it, but the import configuration has a issue https://github.com/gpsinsight/terraform-provider-fusionauth/issues/214 === Importing The Default Tenant -We start by importing the default tenant based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] by adding the following code below to `import.tf`. - -Why importing default tenant is good practice? Manage FusionAuth application related topics is always part of the default tenant, as well as there is not necessarily a need to create a different tenant as you create multiple applications. +Importing the Default tenant is needed if you want to manage it through Terraform as it's created during the initial deployment of FusionAuth. In addition, if you are managing FusionAuth application, it will always be part of the Default tenant. As well as there is no need to create a different tenant for creating applications. //knowledge source https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant -Create an `import.tf` configuration file with the following content: +[NOTE.note] +==== +With the usage of Terraform we suggest you to create your now tenant and applications related to your tenant instead of importing. +==== + +Based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] append the `main.tf` configuration file with the following code and Replace-This-ID-With-Existing-ID with the related ID you can find in the FusionAuth Admin UI. +//TODO: Screenshot Tenant ID [source] ---- import { - to = fusionauth_tenant.default - id = "374eba67-12b0-4957-2a4e-a91a8c6f9bfb" + to = fusionauth_tenant.Default + id = "Replace-This-ID-With-Existing-ID" +} + +resource "fusionauth_tenant" "Default" { + name = "Default" + issuer = "acme.com" + theme_id = "Replace-This-ID-With-Existing-ID" + external_identifier_configuration { + authorization_grant_id_time_to_live_in_seconds = 30 + change_password_id_generator { + length = 32 + type = "randomBytes" + } + change_password_id_time_to_live_in_seconds = 600 + device_code_time_to_live_in_seconds = 300 + device_user_code_id_generator { + length = 6 + type = "randomAlphaNumeric" + } + email_verification_id_generator { + length = 32 + type = "randomBytes" + } + email_verification_id_time_to_live_in_seconds = 86400 + email_verification_one_time_code_generator { + length = 6 + type = "randomAlphaNumeric" + } + external_authentication_id_time_to_live_in_seconds = 300 + one_time_password_time_to_live_in_seconds = 60 + passwordless_login_generator { + length = 32 + type = "randomBytes" + } + passwordless_login_time_to_live_in_seconds = 180 + registration_verification_id_generator { + length = 32 + type = "randomBytes" + } + registration_verification_id_time_to_live_in_seconds = 86400 + registration_verification_one_time_code_generator { + length = 6 + type = "randomAlphaNumeric" + } + saml_v2_authn_request_id_ttl_seconds = 300 + setup_password_id_generator { + length = 32 + type = "randomBytes" + } + setup_password_id_time_to_live_in_seconds = 86400 + two_factor_id_time_to_live_in_seconds = 300 + two_factor_one_time_code_id_generator { + length = 6 + type = "randomDigits" + } + two_factor_trust_id_time_to_live_in_seconds = 2592000 + } + jwt_configuration { + refresh_token_time_to_live_in_minutes = 43200 + time_to_live_in_seconds = 3600 + refresh_token_revocation_policy_on_login_prevented = true + refresh_token_revocation_policy_on_password_change = true + access_token_key_id = "Replace-This-ID-With-Existing-ID" + id_token_key_id = "Replace-This-ID-With-Existing-ID" + } + login_configuration { + require_authentication = true + } + email_configuration { + default_from_email = "change-me@example.com" + default_from_name = "FusionAuth" + host = "localhost" + implicit_email_verification_allowed = true + port = 25 + security = "NONE" + verification_strategy = "ClickableLink" + verify_email = false + verify_email_when_changed = false + forgot_password_email_template_id = "Replace-This-ID-With-Existing-ID" + passwordless_email_template_id = "Replace-This-ID-With-Existing-ID" + set_password_email_template_id = "Replace-This-ID-With-Existing-ID" + } } ---- -And link:https://developer.hashicorp.com/terraform/language/import/generating-configuration[generate] a tenant configuration file from it with the following command which you then can apply: +Once appended run link:https://developer.hashicorp.com/terraform/cli/commands/plan[terraform plan] to check the validity of your configuration. + +If the plan is valid and you are happy with the changes run link:https://developer.hashicorp.com/terraform/cli/commands/apply[terraform apply] [source] ---- -terraform plan -generate-config-out=generated_resources.tf +terraform plan terraform apply ---- +Once imported, Terraform tracks the resource in your state file. You can then manage the imported resource like any other, updating its attributes. With the exception of destroying the default tenant, which normally works in Terraform lifecycle but as in FusionAuth this is a non-deletable tenant this wont work with Terraform either and will break your Terraform state. + +We suggest to leave the import block in your configuration a record of the resource's origin. The import block records that Terraform imported the resource and did not create it. + === Importing The FusionAuth Application -The same works with importing the default FusionAuth application based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] by adding the following code to `import.tf`. +The same works with importing the default FusionAuth application based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] by appending the following code to `main.tf`. [source] ---- import { to = fusionauth_application.FusionAuth - id = "3c219e58-ed0e-4b18-ad48-f4f92793ae32" + id = "Replace-This-ID-With-Existing-ID" +} + +resource "fusionauth_application" "FusionAuth" { + tenant_id = fusionauth_tenant.Default.id + name = "FusionAuth" } ---- +Once appended run link:https://developer.hashicorp.com/terraform/cli/commands/plan[terraform plan] to check the validity of your configuration. + +If the plan is valid and you are happy with the changes run link:https://developer.hashicorp.com/terraform/cli/commands/apply[terraform apply] + +[source] +---- +terraform plan +terraform apply +---- +Once imported, Terraform tracks the resource in your state file. You can then manage the imported resource like any other, updating its attributes. With the exception of destroying the FusionAuth application, which normally works in Terraform lifecycle but as in FusionAuth this is a non-deletable application this wont work with Terraform either and will break your Terraform state. + +We suggest to leave the import block in your configuration a record of the resource's origin. The import block records that Terraform imported the resource and did not create it. + === Terraform Data Source Instead Of Import -Instead of importing a ressource you can use existing configuration as a Data Source instead, the list of all supported data sources you can find in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] +Instead of importing a ressource you can use existing FusionAuth configuration as a Data Source instead, the list of all supported data sources you can find in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] -If you choose to manage the default Tenant and FusionAuth Application outside instead as shown previously inside the Terraform configuration. But still add Applications in to the default Tenant via Terraform, you can reference it in the configuration as a data source. +In the scenario where you choose to manage the Default tenant and FusionAuth application outside Terraform. But still add Applications in to the default Tenant via Terraform, you can reference it in the configuration as a data source. * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/tenant[Terraform Data Source: Application] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/data-sources/application[Terraform Data Source: Application] @@ -147,6 +261,14 @@ data "fusionauth_application" "FusionAuth" { } ---- +[NOTE.note] +==== +If you manage the Default tenant and FusionAuth application outside of Terraform but want specific actions (scripts, API calls, etc.) still integrated and triggered by your Terraform configuration, you could make the use of link:https://developer.hashicorp.com/terraform/language/resources/provisioners/syntax[Provisioners]. + +Terraform includes the concept of provisioners as a measure of pragmatism and last resort (Since provisioners are non-declarative and potentially unpredictable), knowing that there are always certain behaviors that cannot be directly represented in Terraform's declarative model. +==== +//TODO Provisioner https://developer.hashicorp.com/terraform/language/resources/provisioners/syntax + == Terraform Create To create a new resource you can go through the list of resources available to you in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] and pick the ressource you are interested in. Each resource contains information about required and optional arguments. @@ -218,7 +340,7 @@ Once you are happy with your configuration run `terraform plan` and if you are n == Terraform Update -Once a resource is either imported or created you can changing existing attributes accordingly in your existing `.tf` files or add additional ones according to the documentation. +Once a resource is either created or imported you can change your main.tf according to the documentation. * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] @@ -226,7 +348,9 @@ Once a resource is either imported or created you can changing existing attribut * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] -If you want to know what already has been defined by terraform but not specified in your `.tf` files you can run `terraform show`. +After you are done with your configuration changes, run `terraform plan` to check the planned changes and review potential errors. After that you can go ahead with `terraform apply`. + +If you want to know what already has been defined by Terraform but not specified in your `.tf` files you can run `terraform show`. The configuration can get very large and if you want to show only very specific resources you can list all resources with `terraform state list` and show the resource state with `terraform state show ` accordingly. From 8dc7a9ba30435a7c285404a3cd6162c2aa651b70 Mon Sep 17 00:00:00 2001 From: Michael Roth Date: Fri, 7 Jul 2023 20:34:26 +0200 Subject: [PATCH 11/36] refactor(Terraform): review of the latest version, improving hands-on configs --- .../configuration-management/terraform.adoc | 65 +++++++++++++------ 1 file changed, 44 insertions(+), 21 deletions(-) diff --git a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc index 0bd821ab5d..e1f107973d 100644 --- a/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc +++ b/site/docs/v1/tech/admin-guide/configuration-management/terraform.adoc @@ -27,7 +27,7 @@ Since it is a community project, it is not as complete as the client libraries. == Prerequisites -In order for you to get the most value from this guide, you should have a FusionAuth instance set up and Terraform CLI ready in your runtime. +In order to get the most value from this guide, you should have a FusionAuth instance set up and Terraform CLI ready in your runtime. If you don't have this set up yet, please review the following links: @@ -92,34 +92,38 @@ It is always safe to run link:https://developer.hashicorp.com/terraform/cli/comm Before we go in to Creating, Updating and Removing of resources we first look in to the link:https://developer.hashicorp.com/terraform/language/import[Import] functionality. If you have existing resources you want to manage via Terraform you need to import the current configuration to be able to manage it via Terraform. [NOTE.note] ==== -The cleaner way is to create all resources through Terraform instead, but in certain scenarios you will have to use Import or Data Source and we go through a few examples in this ant the next section. +The cleaner way is to create all resources through Terraform instead, but in certain scenarios you will have to use `Import` or `Data Source` and we go through a few examples in this and the next section. ==== //Additional input for documentation tbd. import cli https://developer.hashicorp.com/terraform/cli/import import config https://developer.hashicorp.com/terraform/language/import https://spacelift.io/blog/importing-exisiting-infrastructure-into-terraform https://medium.com/swlh/importing-existing-infrastructure-into-terraform-a6ae168ad2bb https://stackoverflow.com/questions/47613926/import-all-resources-defined-in-tf-file https://www.bitslovers.com/terraform-import/) -// The import and generate config command works and i've tested it, but the import configuration has a issue https://github.com/gpsinsight/terraform-provider-fusionauth/issues/214 +// The import and generate config command works and I've tested it, but the import configuration has a issue https://github.com/gpsinsight/terraform-provider-fusionauth/issues/214 === Importing The Default Tenant -Importing the Default tenant is needed if you want to manage it through Terraform as it's created during the initial deployment of FusionAuth. In addition, if you are managing FusionAuth application, it will always be part of the Default tenant. As well as there is no need to create a different tenant for creating applications. +Importing the Default tenant is required if you want to manage it through Terraform as it's created during the initial deployment of FusionAuth. In addition, if you are managing FusionAuth application, it will always be part of the Default tenant. As well as there is no need to create a different tenant for creating applications. //knowledge source https://fusionauth.io/community/forum/topic/1725/what-are-the-pros-and-cons-of-using-the-default-tenant [NOTE.note] ==== -With the usage of Terraform we suggest you to create your now tenant and applications related to your tenant instead of importing. +With the usage of Terraform we suggest you to create your own tenant and applications related to your tenant instead of importing. ==== -Based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] append the `main.tf` configuration file with the following code and Replace-This-ID-With-Existing-ID with the related ID you can find in the FusionAuth Admin UI. -//TODO: Screenshot Tenant ID +Based on the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/tenant[Terraform Resource: Tenant] append the `main.tf` configuration file with the following code and replace the UUIDs with the related Ids of your FusionAuth Instance. + +To make things easier, we only replace the first Id in the import section with the `Default Tenant Id`, you can find it in the FusionAuth Admin UI under `Tenants` and we leave all the other UUID definitions 00000000-0000-0000-0000-000000000000 as they are, we will replace them in the next step. + + +//TODO: Screenshot Tenant Id [source] ---- import { to = fusionauth_tenant.Default - id = "Replace-This-ID-With-Existing-ID" + id = "Replace-This-With-The-Existing-Default-Tenant-Id" } resource "fusionauth_tenant" "Default" { name = "Default" issuer = "acme.com" - theme_id = "Replace-This-ID-With-Existing-ID" + theme_id = "00000000-0000-0000-0000-000000000000" external_identifier_configuration { authorization_grant_id_time_to_live_in_seconds = 30 change_password_id_generator { @@ -175,8 +179,8 @@ resource "fusionauth_tenant" "Default" { time_to_live_in_seconds = 3600 refresh_token_revocation_policy_on_login_prevented = true refresh_token_revocation_policy_on_password_change = true - access_token_key_id = "Replace-This-ID-With-Existing-ID" - id_token_key_id = "Replace-This-ID-With-Existing-ID" + access_token_key_id = "00000000-0000-0000-0000-000000000000" + id_token_key_id = "00000000-0000-0000-0000-000000000000" } login_configuration { require_authentication = true @@ -191,12 +195,30 @@ resource "fusionauth_tenant" "Default" { verification_strategy = "ClickableLink" verify_email = false verify_email_when_changed = false - forgot_password_email_template_id = "Replace-This-ID-With-Existing-ID" - passwordless_email_template_id = "Replace-This-ID-With-Existing-ID" - set_password_email_template_id = "Replace-This-ID-With-Existing-ID" + forgot_password_email_template_id = "00000000-0000-0000-0000-000000000000" + passwordless_email_template_id = "00000000-0000-0000-0000-000000000000" + set_password_email_template_id = "00000000-0000-0000-0000-000000000000" } } ---- +Now as we provided our `Tenant Id` we let terraform find our other Ids which we have to replace in the `main.tf` file. +[source] +---- +terraform plan | grep 0000 +---- +It wants to replace several Id definitions with 00000000-0000-0000-0000-000000000000, but we don't want to do that, instead we will copy the Ids to our `main.tf` file and replace the 00000000-0000-0000-0000-000000000000's with them. + +Here is how the output should look like: +[source] +---- +~ theme_id = "75a068fd-e94b-451a-9aeb-3ddb9a3b5987" -> "00000000-0000-0000-0000-000000000000" +~ forgot_password_email_template_id = "03c264a2-9c89-4fb2-a78b-4333b9485d99" -> "00000000-0000-0000-0000-000000000000" +~ passwordless_email_template_id = "8e95e7ca-104a-48ce-86d1-aa39e2c71d51" -> "00000000-0000-0000-0000-000000000000" +~ set_password_email_template_id = "6752116b-9f34-4e66-98ef-438258edeb18" -> "00000000-0000-0000-0000-000000000000" +~ access_token_key_id = "12c6b146-89cf-9473-490b-1c97e4e68674" -> "00000000-0000-0000-0000-000000000000" +~ id_token_key_id = "092dbedc-30af-4149-9c61-b578f2c72f59" -> "00000000-0000-0000-0000-000000000000" +---- +Make sure you copy all those Id's from your output to the `main.tf` file. Once appended run link:https://developer.hashicorp.com/terraform/cli/commands/plan[terraform plan] to check the validity of your configuration. @@ -219,7 +241,7 @@ The same works with importing the default FusionAuth application based on the li ---- import { to = fusionauth_application.FusionAuth - id = "Replace-This-ID-With-Existing-ID" + id = "00000000-0000-0000-0000-000000000000" } resource "fusionauth_application" "FusionAuth" { @@ -227,6 +249,7 @@ resource "fusionauth_application" "FusionAuth" { name = "FusionAuth" } ---- +Replace the 00000000-0000-0000-0000-000000000000 with your `FusionAuth Application Id`, you can find it in the `FusionAuth Admin UI` under `Applications`. Once appended run link:https://developer.hashicorp.com/terraform/cli/commands/plan[terraform plan] to check the validity of your configuration. @@ -243,7 +266,7 @@ We suggest to leave the import block in your configuration a record of the resou === Terraform Data Source Instead Of Import -Instead of importing a ressource you can use existing FusionAuth configuration as a Data Source instead, the list of all supported data sources you can find in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] +Instead of importing a resource you can use existing FusionAuth configuration as a `Data Source`, the list of all supported data sources you can find in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] In the scenario where you choose to manage the Default tenant and FusionAuth application outside Terraform. But still add Applications in to the default Tenant via Terraform, you can reference it in the configuration as a data source. @@ -252,7 +275,7 @@ In the scenario where you choose to manage the Default tenant and FusionAuth app [source] ---- -data "fusionauth_tenant" "default" { +data "fusionauth_tenant" "Default" { name = "Default" } @@ -271,21 +294,21 @@ Terraform includes the concept of provisioners as a measure of pragmatism and la == Terraform Create -To create a new resource you can go through the list of resources available to you in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] and pick the ressource you are interested in. Each resource contains information about required and optional arguments. +To create a new resource you can go through the list of resources available to you in the link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs[FusionAuth Terraform Provider Documentation] and pick the resource you are interested in. Each resource contains information about required and optional arguments. -In this example we create an Application called forum in the default Tenant with related Roles (admin and user), Users (forum-user1 and forum-admin1) and according Registrations: +In this example we create an application called forum in the Default tenant with related roles (admin and user), users (forum-user1 and forum-admin1) and according registrations: * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application[Terraform Resource: Application] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/application_role[Terraform Resource: Application Role] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/user[Terraform Resource: User] * link:https://registry.terraform.io/providers/gpsinsight/fusionauth/latest/docs/resources/registration[Terraform Resource: Registration] -For referenced IDs which are Data Sources use a leading `data.` for the specification e.g. `tenant_id = data.fusionauth_tenant.default.id`. +For referenced Ids which are `Data Sources` use a leading `data.` for the specification e.g. `tenant_id = data.fusionauth_tenant.Default.id`, if you used the import without using `Data Sources` you have to remove the leading `data.` from the following resource definitions, otherwise it terraform plan will throw an error. [source] ---- resource "fusionauth_application" "forum" { - tenant_id = data.fusionauth_tenant.default.id + tenant_id = data.fusionauth_tenant.Default.id name = "forum" } From a212769d2f2fceac2acd1624d24dd5fc09d343de Mon Sep 17 00:00:00 2001 From: Aaron Ritter Date: Fri, 14 Jul 2023 13:26:48 +0200 Subject: [PATCH 12/36] refactor(terraform): update guide with additional feedback - added configuration strategies table overview - added subject to change - added lifecycle ignore_changes to update section - reformat all source sections with same indents --- fusionauth-site.ipr | 27 +- .../configuration-management/terraform.adoc | 344 +++++++++++------- 2 files changed, 245 insertions(+), 126 deletions(-) diff --git a/fusionauth-site.ipr b/fusionauth-site.ipr index 765d15792c..4d4dbf7a1e 100644 --- a/fusionauth-site.ipr +++ b/fusionauth-site.ipr @@ -817,6 +817,12 @@ + + + + + + + + + + + + + + + + - - - - - - - -