docs: slz customization documentation, teleport, big-ip (#123)

Co-authored-by: Allen Dean <[email protected]>

.docs/bastion/bastion.md

@@ -0,0 +1,132 @@
+# Provisioning a bastion host by using Teleport with Secure Landing Zone
+
+Secure Landing Zone can provision the solution that is described in [Setting up a bastion host that uses Teleport](https://cloud.ibm.com/docs/allowlist/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-bastion-tutorial-teleport) (available by allowlist). This solution configures a bastion host in your VPC using Teleport Enterprise Edition, and provisions a Cloud Object Storage bucket and App ID for enhanced security.
+
+[App ID](https://cloud.ibm.com/docs/appid) is used to authenticate users to Teleport. Teleport session recordings are stored in the Object Storage bucket. The [cloud-init file](../../teleport_config/cloud-init.tpl) file installs teleport and configures App ID and Object Storage. The Teleport [variables.tf](../../teleport_config/variables.tf) file is used for the configuration.
+
+## Before you begin
+
+You need the following items to deploy and configure a bastion host that uses Teleport:
+
+- A Teleport Enterprise Edition license
+- A generated SSL certificate and key for each of the provisioned virtual server instances or a wildcard certificate
+
+## Provision with Secure Landing Zone
+
+SLZ can provision the bastion host in two locations. You can place the bastion either within the management VPC or in the edge VPC if you're using BIG-IP from F5.
+
+| Management VPC                                     | Edge or Transit VPC           |
+| ---------------------------------------------------| ----------------------------- |
+| ![Management](../images/management-teleport.png)   | ![Edge](../images/edge-f5.png)|
+
+### Provisioning a bastion host in the management VPC
+
+To provision Teleport within the management zone, you must set `teleport_management_zones` to the number of bastion hosts to deploy, up to a maximum of 3. For example, if you set the number to `1`, it provisions a bastion host in zone-1 of your management VPC. If you set the number to `2`, it provisions a bastion within zone-1 and zone-2 of your management VPC. Other variables that are needed for the setup and configuration of Teleport are mentioned in the following sections.
+
+### Provisioning a bastion host on the edge VPC with F5 BIG-IP
+
+The `provision_teleport_in_f5` and `add_edge_vpc` variables must both be set to true. For more information about F5 deployment, see [Provisioning a F5 BIG-IP host by using Secure Landing Zone](../f5-big-ip/f5-big-ip.md) and the following variables that are needed for the setup and configuration of Teleport.
+
+Don't set both `create_f5_network_on_management_vpc` to true and `teleport_management_zones` to a value greater than `0`.
+
+### Teleport configuration variables
+
+The following variables need to be set to provision the bastion host using Teleport.
+
+```
+provision_teleport_in_f5  # Provision Teleport in the Edge VPC alongside the F5
+use_existing_appid        # Use an existing appid instance. If this is false, one will be automatically
+appid_name                # Name of appid instance.
+appid_resource_group      # Resource group for existing appid instance. This value is ignored if a new instance is created.
+teleport_instance_profile # Machine type for Teleport VSI instances. Use the IBM Cloud CLI command `ibmcloud is instance-profiles` to see available image profiles.
+teleport_vsi_image_name   # Teleport VSI image name. Use the IBM Cloud CLI command `ibmcloud is images` to see available images.
+teleport_license          # The contents of the PEM license file
+https_cert                # The https certificate used by bastion host for teleport
+https_key                 # The https private key used by bastion host for teleport
+teleport_hostname         # The name of the instance or bastion host
+teleport_domain           # The domain of the bastion host
+teleport_version          # Version of Teleport Enterprise to use
+message_of_the_day        # Banner message that is exposed to the user at authentication time
+teleport_admin_email      # Email for teleport vsi admin.
+teleport_management_zones # Number of zones to create teleport VSI on Management VPC if not using F5. If you are using F5, ignore this value
+```
+
+For more details about specifying input variables, see [Customizing your environment](../../README.md#customizing-your-environment). For more information about the Teleport configuration variables, see the following documentation for the pattern:
+
+- [VSI](../../patterns/vsi/README.md#module-variables)
+- [Mixed](../../patterns/mixed/README.md#module-variables)
+- [ROKS](../../patterns/roks/README.md#module-variables)
+
+## Accessing Teleport
+
+After App ID is successfully configured to Teleport, you can log in to Teleport through a web console or tsh client. Tsh is the Teleport client tool that is the command-line tool for Teleport. For more information, see [Installing tsh](https://goteleport.com/docs/server-access/guides/tsh/#installing-tsh). You need the fully qualified domain name (FQDN) of the Teleport server to log in.
+
+### Log in through the web console
+
+1.  Access the web console on port 3080. (`https://<User defined FQDN of teleport server>:3080`).
+1.  Start a terminal session under **Servers**. Look for a single server with a connect button. Click **Connect** and select the user that you would like to log in with.
+
+### Log in through the tsh client
+
+1.  Install the [Teleport client tool tsh](https://goteleport.com/docs/server-access/guides/tsh/#installing-tsh).
+1.  [Log in using tsh](https://goteleport.com/docs/server-access/guides/tsh/#logging-in).
+
+    ```sh
+    tsh login --proxy=<User defined FQDN of teleport server>:3080
+    ```
+
+1.  Run the shell or run a command on a remote SSH node by using the [tsh ssh command](https://goteleport.com/docs/setup/reference/cli/#tsh-ssh).
+
+    ```sh
+    tsh ssh <[user@]host>
+    ```
+
+## Debugging bastion host VSI
+
+You might not be able to access Teleport that is installed on your virtual server after the bastion host is provisioned by the Secure Landing Zone. Follow these steps to login and verify the configuration of your virtual server through SSH.
+
+1.  Connect to your bastion host VSI by using [SSH](https://cloud.ibm.com/docs/vpc?topic=vpc-vsi_is_connecting_linux).
+
+    :information_source: **Tip:** SSH is not allowed by default. You must add rules to the [security groups](https://cloud.ibm.com/vpc-ext/network/securityGroups) and [ACLs](https://cloud.ibm.com/vpc-ext/network/acl) on our virtual server.
+
+1.  Run each of the following commands and check whether the values match the ones that you configured:
+
+    1.  Verify whether the content of the file matches your `teleport_license`:
+
+        ```sh
+        cat ~/license.pem
+        ```
+    1.  Verify whether the content of the file matches your `https_cert`:
+
+        ```sh
+        cat ~/cert.pem
+        ```
+
+    1.  Verify whether the content of the file equals your `https_key`:
+
+        ```sh
+        cat ~/key.pem
+        ```
+
+    1.  Verify both that the `redirect_url` value equals `https://<HOSTNAME>.<DOMAIN>:3080/v1/webapi/oidc/callback` and that the `claims_to_roles` value is `- {claim: "email", value: "<TELEPORT_ADMIN_EMAIL>", roles: ["teleport-admin"]}`:
+
+        ```sh
+        cat ~/oidc.yaml
+        ```
+
+    1.  Verify whether the `audit_sessions_uri` value contains your `cos_bucket_name`:
+
+        ```sh
+        cat ~/../etc/teleport.yaml
+        ```
+    1.  Verify that Teleport is running:
+
+        ```sh
+        systemctl status teleport
+        ```
+
+1.  After you verify that Teleport is configured correctly, remove the security group and ACL rules you added in Step 1. Alternatively, you can run the script `/root/install.sh` to run the installation again.
+
+## ACL and security groups
+
+By default, Secure Landing Zone provisions ACLs and security groups that are more open and not customer dependent. Use the [override.json](../../README.md#customizing-by-using-the-overridejson-file) file to change, add, or delete rules for your environment.

.docs/f5-big-ip/f5-big-ip.md

@@ -0,0 +1,106 @@
+# Provisioning a F5 BIG-IP host by using Secure Landing Zone
+
+Through Secure Landing Zone, you can optionally provision the F5 BIG-IP so that you can set up the implemented solution of a client-to-site VPN or web application firewall (WAF). For more information, see [Deploying and configuring F5 BIG-IP](https://cloud.ibm.com/docs/allowlist/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-f5-tutorial) (available by allowlist).
+
+## Before you begin
+
+You need the following items to deploy and configure the reference architecture that is described in Deploying and configuring F5 BIG-IP:
+
+- F5 BIG-IP Virtual Edition license
+- Additional IAM VPC Infrastructure Service service access of `IP Spoofing operator`
+- [Contact support](https://cloud.ibm.com/unifiedsupport/cases/form) to increase the quota for subnets for each VPC. Thirty subnets per VPC cover most cases.
+
+    The following chart shows the number of subnets that you need, depending on your F5 BIG-IP deployment.
+
+    | Service     | # of subnets without bastion | # of subnets with bastion |
+    | ----------- | ---------------------------- | ------------------------- |
+    | VPN and WAF | 21                           | 24                        |
+    | Full-tunnel | 18                           | 21
+    | WAF         | 15                           | 18
+
+    The following chart lists the CIDR blocks and the zones that each type is deployed. Additional subnets for VPEs are also provisioned along with bastion host, if that host is used.
+
+    | CIDRs        | Zone        | WAF    | Full-tunnel    | VPN-and-WAF    |
+    | ------------ | ----------- | :----: | :------------: | :------------: |
+    | 10.5.10.0/24 | zone-1      | X      | X              | X              |
+    | 10.5.20.0/24 | zone-1      | X      | X              | X              |
+    | 10.5.30.0/24 | zone-1      | X      | X              | X              |
+    | 10.5.40.0/24 | zone-1      |        | X              | X              |
+    | 10.5.50.0/24 | zone-1      |        | X              | X              |
+    | 10.5.60.0/24 | zone-1      |        |                | X              |
+    | 10.6.10.0/24 | zone-2      | X      | X              | X              |
+    | 10.6.20.0/24 | zone-2      | X      | X              | X              |
+    | 10.6.30.0/24 | zone-2      | X      | X              | X              |
+    | 10.6.40.0/24 | zone-2      |        | X              | X              |
+    | 10.6.50.0/24 | zone-2      |        | X              | X              |
+    | 10.6.60.0/24 | zone-2      |        |                | X              |
+    | 10.7.10.0/24 | zone-3      | X      | X              | X              |
+    | 10.7.20.0/24 | zone-3      | X      | X              | X              |
+    | 10.7.30.0/24 | zone-3      | X      | X              | X              |
+    | 10.7.40.0/24 | zone-3      |        | X              | X              |
+    | 10.7.50.0/24 | zone-3      |        | X              | X              |
+    | 10.7.60.0/24 | zone-3      |        |                | X              |
+
+## Provision with Secure Landing Zone
+
+The F5 BIG-IP can be provisioned in the management or edge/transit VPC. In this case, use the edge/transit VPC. By default, it provisions an F5 BIG-IP within each zone of the region. You can change this setting in the [override.json](../../README.md#customizing-by-using-the-overridejson-file) file.
+
+| Management VPC                               | Edge/Transit VPC              |
+| -------------------------------------------- | ----------------------------- |
+| ![Management](../images/f5-management.png)   | ![Edge](../images/edge-f5.png)|
+
+### F5 BIG-IP configuration variables
+
+Some of the configuration variables are optional, but several are needed to provision the F5 BIG-IP. The following variables are important:
+
+```
+add_edge_vpc                        # Automatically adds the edge/transit VPC along with the F5 BIG-IP
+create_f5_network_on_management_vpc # Provision the F5 BIG-IP in the management VPC
+provision_teleport_on_f5            # Provision Teleport bastion hosts within the edge VPC. See bastion documentation for more information about bastion hosts
+vpn_firewall_type                   # The type of service you are using the BIG-IP for (full-tunnel, waf, vpn-and-waf). This is required if you enable the F5 BIG-IP
+hostname                            # Hostname of the F5 BIG-IP
+domain                              # The domain name of the F5 BIG-IP
+tmos_admin_password                 # The admin password to log into the management console (Requirements: Minimum length of 15 characters/Required Characters: Numeric = 1, Uppercase = 1, Lowercase = 1)
+enable_f5_external_fip              # Enable a FIP on the external interface. Default is true
+enable_f5_management_fip            # Enable a FIP on the management interface. Default is false
+```
+
+The following example shows how to provision an F5 with the following configuration:
+
+- Create an edge/transit VPC
+- Provision an F5 BIG-IP with the architecture setup for WAF in each zone
+- Do not provision bastion host within the edge VPC
+- Set the hostname to `example`
+- Set the domain to `test.com`
+- Set the console login to `Hello12345World`
+- Enable a floating IP the external interface
+
+   ```
+   add_edge_vpc                        = true
+   create_f5_network_on_management_vpc = false
+   provision_teleport_on_f5            = false
+   vpn_firewall_type                   = "waf"
+   hostname                            = "example"
+   domain                              = "test.com"
+   tmos_admin_password                 = "Hello12345World" <!-- pragma: allowlist secret -->
+   enable_f5_external_fip              = true
+   enable_f5_management_fip            = false
+   ```
+
+For more details about specifying input variables, see [Customizing your environment](../../README.md#customizing-your-environment). For more information about the F5 configuration variables, see the following documentation for the pattern:
+
+- [VSI](../../patterns/vsi#module-variables)
+- [Mixed](../../patterns/mixed#module-variables)
+- [ROKS](../../patterns/roks#module-variables)
+
+### Accessing the F5 BIG-IP
+
+You might not be able to access management console by floating IP address (if enabled) that is provisioned on your virtual server instance either on the management or external interface. Use the `tmos_admin_password` that you set earlier to access it.
+
+### Setup of the client-to-site VPN and WAF
+
+For more information about how to set up the client-to-site VPN and WAF, see [Deploying and configuring F5 BIG-IP](https://cloud.ibm.com/docs/allowlist/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-f5-tutorial) (available by allowlist).
+
+### ACL and security groups
+
+By default, Secure Landing Zone provisions ACLs and security groups that are more open and not customer dependent. Use the [override.json](../../README.md#using-overridejson) file to change, add, or delete rules for your environment.