Skip to content
Snippets Groups Projects
Commit 8eb2eb95 authored by Nuwan Rajika Kumarasiri's avatar Nuwan Rajika Kumarasiri
Browse files

Merge branch 'userguide' into 'master' 

Add a user guide for Secure Agent documentation - WISCALERTS-27

See merge request !16
parents 3f7b6c1a 86eb1b81
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
README.md
+ 49
− 4
View file @ 8eb2eb95
## Table Of Contents
* [User Guide](#user-guide)
* [IICS Secure Agent Docker Image](#iics-secure-agent-docker-image)
* [Description](#description)
* [Requirements](#requirements)
* [The Image](#the-image)
* [Containers](#containers)
* [Environment Variables](#environment-variables)
* [Externalized Configurations](#externalized-configurations)
* [Starting](#starting)
* [Monitoring](#monitoring)
* [Hardware Requirements](#hardware-requirements)
* [Known Issues](#known-issues)
* [Enterprise Integration Secure Agent](#enterprise-integration-secure-agent)
* [Architecture Diagram](#architecture-diagram)
* [CI/CD and Terraform](#cicd-and-terraform)
* [Informatica User](#informatica-user)
* [Credentials in Terraform](#credentials-in-terraform)
* [Test Environment](#test-environment)
* [Production Environment](#production-environment)
* [Memory and CPU for Secure Agent](#memory-and-cpu-for-secure-agent)
* [EFS Mounting, Accessing Secure Agent Configurations, Logs and Additional Debugging](#efs-mounting-accessing-secure-agent-configurations-logs-and-additional-debugging)
# User Guide
[userguide]: #user-guide
User guide for AWS hosted Secure Agent is available [here](./userguide.md).
# IICS Secure Agent Docker Image # IICS Secure Agent Docker Image
[dockerimage]: #iics-secure-agent-docker-image
This document covers following topics: This document covers following topics:
1. How ro run IICS Secure Agent using Docker image. 1. How ro run IICS Secure Agent using Docker image.
2. IICS Secure Agent deployed(including Terraform configuration) in AWS(interop). 2. IICS Secure Agent deployed(including Terraform configuration) in AWS(interop).
## Description ## Description
[description]: #description
This project was forked from [jbrazda/ic-sagent-docker](https://github.com/jbrazda/ic-sagent-docker) with the intention of containerizing the IICS Secure Agent to run in Amazon Web Services. As of early January 2019, there is no official Docker image for IICS Secure Agent. This project was forked from [jbrazda/ic-sagent-docker](https://github.com/jbrazda/ic-sagent-docker) with the intention of containerizing the IICS Secure Agent to run in Amazon Web Services. As of early January 2019, there is no official Docker image for IICS Secure Agent.
## Requirements ## Requirements
[requirement]: #requirements
* Docker. * Docker.
* An IICS user account and password for your organization that has appropriate rights to create and manage secure agents. This user will be used to login to the Informatica APIs to register the agent. * An IICS user account and password for your organization that has appropriate rights to create and manage secure agents. This user will be used to login to the Informatica APIs to register the agent.
* Your Informatica POD and REGION, which can be inferred from https://${POD}.${REGION}.informaticacloud.com/. Defaults are set to POD=usw3 and REGION=dm-us, but can be overriden with Docker environment variables. * Your Informatica POD and REGION, which can be inferred from https://${POD}.${REGION}.informaticacloud.com/. Defaults are set to POD=usw3 and REGION=dm-us, but can be overriden with Docker environment variables.
## The Image ## The Image
[image]: #the-image
The image is based on Ubuntu 18.04. It downloads and installs necessary dependencies, and then downloads the installer file from the correct Informatica URL based on your POD and REGION. The image is based on Ubuntu 18.04. It downloads and installs necessary dependencies, and then downloads the installer file from the correct Informatica URL based on your POD and REGION.
1. Clone this repository. 1. Clone this repository.
2. `docker build . -t iics_secure_agent:<tag>` - optionally pass --build-arg parameters for POD and REGION if the defaults are not correct. POD and REGION are also set as environment variables, because containers will use these values for communicating with the Informatica API. 2. `docker build . -t iics_secure_agent:<tag>` - optionally pass --build-arg parameters for POD and REGION if the defaults are not correct. POD and REGION are also set as environment variables, because containers will use these values for communicating with the Informatica API.
## Containers ## Containers
[container]: #containers
The container executes a bash script called run_agent.sh upon start. It needs INFORMATICA_USER and INFORMATICA_PASSWORD environment variables set during runtime in order to communicate with the Informatica API to check and register the Secure Agent. The container executes a bash script called run_agent.sh upon start. It needs INFORMATICA_USER and INFORMATICA_PASSWORD environment variables set during runtime in order to communicate with the Informatica API to check and register the Secure Agent.
### Environment Variables ### Environment Variables
[variables]: #environment-variables
* INFORMATICA_USER (required) - User that can run the agent and access Informatica APIs * INFORMATICA_USER (required) - User that can run the agent and access Informatica APIs
* INFORMATICA_PASSWORD (required) - Password for above credential. Used for API access only. * INFORMATICA_PASSWORD (required) - Password for above credential. Used for API access only.
* JSON_LOG (optional) - If this is set, then the log output will be in JSON format. * JSON_LOG (optional) - If this is set, then the log output will be in JSON format.
### Externalized Configurations ### Externalized Configurations
[configs]: #externalized-configurations
Secure Agent's configurations can be externalized using Docker [volumes](https://docs.docker.com/storage/volumes/). Following Secure Agent's configurations can be externalized using Docker [volumes](https://docs.docker.com/storage/volumes/). Following
Secure Agent's directories and files can be externalized for containers. Note that after initial Secure Agent's directories and files can be externalized for containers. Note that after initial
container startup, these configurations can be used to start subsequent containers. container startup, these configurations can be used to start subsequent containers.
...@@ -46,7 +80,7 @@ Following ports(among others) in Secure Agents can be mapped to host for externa ...@@ -46,7 +80,7 @@ Following ports(among others) in Secure Agents can be mapped to host for externa
See below section for examples on how to use volume and port mapping. See below section for examples on how to use volume and port mapping.
### Starting ### Starting
[starting]: #starting
* Setting the hostname will provide the associated name in the IICS website. * Setting the hostname will provide the associated name in the IICS website.
* Note: since anybody who has access to see the processes can view the values `INFORMATICA_USER` and `INFORMATICA_PASSWORD`, it's * Note: since anybody who has access to see the processes can view the values `INFORMATICA_USER` and `INFORMATICA_PASSWORD`, it's
recommenced to configure them in a Docker [.env](https://docs.docker.com/compose/env-file/) file. recommenced to configure them in a Docker [.env](https://docs.docker.com/compose/env-file/) file.
...@@ -86,6 +120,7 @@ $ docker run -d \ ...@@ -86,6 +120,7 @@ $ docker run -d \
``` ```
### Monitoring ### Monitoring
[monitor]: #monitoring
If volume mapping is not used use `docke exec` to attach to the running container. If volume mapping is not used use `docke exec` to attach to the running container.
```shell ```shell
...@@ -93,6 +128,7 @@ docker exec -it <container_name> less agentCore.log ...@@ -93,6 +128,7 @@ docker exec -it <container_name> less agentCore.log
``` ```
## Hardware Requirements ## Hardware Requirements
[hardware]: #hardware-requirements
Minimum Hardware Specs ([reference](https://network.informatica.com/servlet/JiveServlet/download/189174-25674/Informatica%20Cloud%20Secure%20Agent%20Minimum%20Requirements.pdf)): Minimum Hardware Specs ([reference](https://network.informatica.com/servlet/JiveServlet/download/189174-25674/Informatica%20Cloud%20Secure%20Agent%20Minimum%20Requirements.pdf)):
* Windows version 7 (32-bit or 64-bit) or Windows XP Pro SP2/SP3 (32-bit). * Windows version 7 (32-bit or 64-bit) or Windows XP Pro SP2/SP3 (32-bit).
* Linux (32-bit or 64-bit). * Linux (32-bit or 64-bit).
...@@ -104,9 +140,11 @@ Minimum Hardware Specs ([reference](https://network.informatica.com/servlet/Jive ...@@ -104,9 +140,11 @@ Minimum Hardware Specs ([reference](https://network.informatica.com/servlet/Jive
* 1 GB Network connectivity (faster the better as this will most likely the bottleneck). * 1 GB Network connectivity (faster the better as this will most likely the bottleneck).
## Known Issues ## Known Issues
[issues]: #known-issues
* Doesn't seem to be able to run in host network mode because it won't be able to talk to internal ports. It would probably work if you expose those ports. * Doesn't seem to be able to run in host network mode because it won't be able to talk to internal ports. It would probably work if you expose those ports.
## Enterprise Integration Secure Agent ## Enterprise Integration Secure Agent
[eisecureagnet]: #enterprise-integration-secure-agent
Secure Agent containers are deployed in following tiers in interop/AWS account. This deployment is automated through Terraform (see below section on Terraform). Secure Agent containers are deployed in following tiers in interop/AWS account. This deployment is automated through Terraform (see below section on Terraform).
| environment| tier |runtime name(default) in IICS | | environment| tier |runtime name(default) in IICS |
...@@ -121,6 +159,7 @@ Secure Agent containers are deployed in following tiers in interop/AWS account. ...@@ -121,6 +159,7 @@ Secure Agent containers are deployed in following tiers in interop/AWS account.
The diagram source can be found [here](https://www.lucidchart.com/documents/edit/86359940-c63f-492c-8dd5-606b90525b92/0_0?beaconFlowId=C00A2449A556180D). The diagram source can be found [here](https://www.lucidchart.com/documents/edit/86359940-c63f-492c-8dd5-606b90525b92/0_0?beaconFlowId=C00A2449A556180D).
### CI/CD and Terraform ### CI/CD and Terraform
[terraform]: #cicd-and-terraform
* Infrastructure is available as code in terraform for `AWS` provider, and [.gitlab-ci.yml](.gitlab-ci.yml) pipeline push the Secure Agent * Infrastructure is available as code in terraform for `AWS` provider, and [.gitlab-ci.yml](.gitlab-ci.yml) pipeline push the Secure Agent
image into [AWS ECR](https://aws.amazon.com/ecr/). image into [AWS ECR](https://aws.amazon.com/ecr/).
* Before disposing and create a new instance of Informatica Secure Agent, existing live connections to various targets(for e.g. databases) * Before disposing and create a new instance of Informatica Secure Agent, existing live connections to various targets(for e.g. databases)
...@@ -137,25 +176,29 @@ in `infaagent.ini` using `InfaAgent.GroupName=aws-interop`). ...@@ -137,25 +176,29 @@ in `infaagent.ini` using `InfaAgent.GroupName=aws-interop`).
* Terraform state files are stored in shared S3 buckets `test-interop-terraform-state` and `prod-interop-terraform-state`. * Terraform state files are stored in shared S3 buckets `test-interop-terraform-state` and `prod-interop-terraform-state`.
### Informatica User ### Informatica User
[user]: #informatica-user
Credentials for Informatica User (for test and prod instances) are stored in parameter store (in regions `us-east-1` and Credentials for Informatica User (for test and prod instances) are stored in parameter store (in regions `us-east-1` and
`us-east-2` respectively) and expected to be available with the following names: `us-east-2` respectively) and expected to be available with the following names:
* username - `/iics/cicd_username`. * username - `/iics/cicd_username`.
* password - `/iics/cicd_password`. * password - `/iics/cicd_password`.
### Credentials in Terraform ### Credentials in Terraform
[cred]: #credentials-in-terraform
* It's recommended to define all variables values in a `*.tfvars` file and pass that to terraform using `-var-file` argument. * It's recommended to define all variables values in a `*.tfvars` file and pass that to terraform using `-var-file` argument.
This will avoid having any sensitive parameters in bash history. This will avoid having any sensitive parameters in bash history.
```shell script ```shell script
$ cd terraform $ cd terraform
``` ```
#### Test Environment #### Test Environment
[testenv]: #test-environment
```shell script ```shell script
$ terraform init -backend-config="bucket=test-interop-terraform-state" \ $ terraform init -backend-config="bucket=test-interop-terraform-state" \
-backend-config="key=ei.secureagent.tfstate" \ -backend-config="key=ei.secureagent.tfstate" \
-backend-config="region=us-east-1" -backend-config="region=us-east-1"
``` ```
#### Production Environment #### Production Environment
[prodenv]: #production-environment
```shell script ```shell script
$ terraform init -backend-config="bucket=prod-interop-terraform-state" \ $ terraform init -backend-config="bucket=prod-interop-terraform-state" \
-backend-config="key=ei.secureagent.tfstate" \ -backend-config="key=ei.secureagent.tfstate" \
...@@ -173,14 +216,16 @@ $ terraform apply "agent.tfplan" ...@@ -173,14 +216,16 @@ $ terraform apply "agent.tfplan"
``` ```
### Memory and CPU for Secure Agent ### Memory and CPU for Secure Agent
[memory]: #memory-and-cpu-for-secure-agent
* By default, Secure Agent is deployed on to a `t2.xlarge` instance and container is given an 15GB of memory. `instance_type` * By default, Secure Agent is deployed on to a `t2.xlarge` instance and container is given an 15GB of memory. `instance_type`
and `container_memory` variables can be used to adjust these values. See [variables.tf](./terraform/variables.tf) for details. and `container_memory` variables can be used to adjust these values. See [variables.tf](./terraform/variables.tf) for details.
### EFS Mounting, Accessing Secure Agent Configurations, Logs and Additional Debugging ### EFS Mounting, Accessing Secure Agent Configurations, Logs and Additional Debugging
[debug]: #efs-mounting-accessing-secure-agent-configurations-logs-and-additional-debugging
* Above terraform configuration creates a EFS file system that is used by the container to persist Secure Agent configurations * Above terraform configuration creates a EFS file system that is used by the container to persist Secure Agent configurations
and logs files. and logs files.
* One way to access Secure Agent's log files and configurations files is to mount the EFS file system use by Secure Agent. * One way to access Secure Agent's log files and configurations files is to mount the EFS file system use by Secure Agent.
EFS file system is accessible from any instance within `test` and `prod` tiers. Start an EC2 instance in `test-tier` VPC EFS file system is accessible from any instance within `test` and `prod` tiers. Start an EC2 instance in `test-tier` VPC
(or in prod VPC - `prod-tier `) and this instance can be used to mount the EFS file system (be sure to that this EC2 instance can be accessed from SSH). (or in prod VPC - `prod-tier `) and this instance can be used to mount the EFS file system (be sure to that this EC2 instance can be accessed from SSH).
Then use the instructions documented in `Settings` in Secure Agent's EFS file system(`iics-secure-agent`) under `File system access` in AWS console. Then use the instructions documented in `Settings` in Secure Agent's EFS file system(`iics-secure-agent`) under `File system access` in AWS console.
* If there's a requirement to log into EC2 instance that runs the container, [AWS Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) can be [used](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-quick-setup.html). * If there's a requirement to log into EC2 instance that runs the container, [AWS Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) can be [used](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-quick-setup.html).
\ No newline at end of file
userguide.md 0 → 100644
+ 25
− 0
View file @ 8eb2eb95
## Table Of Contents
* [User Guide](#user-guide)
* [Enterprise Integration Secure Agent](#enterprise-integration-secure-agent)
* [Where To Get Support ?](#where-to-get-support-)
# User Guide
[userguide]: #user-guide
This is the user guide for AWS hosted Secure Agent from Enterprise Integration team. This Secure Agent can be selected
using the runtime names given in below table in IICS.
## Enterprise Integration Secure Agent
[eisecureagent]: #enterprise-integration-secure-agent
Secure Agent has following IP addresses. If any integration requires access to resources that are
behind the cooperate firewalls(for example a database), a firewall exception for incoming traffic will require for
following IP addresses.
| environment| IP address |runtime name in IICS |
| -----------|-------------|-------------------------|
| test | 3.230.240.5|test.ei.secureagent.doit.wisc.edu |
| prod | 3.19.12.147|prod.ei.secureagent.doit.wisc.edu|
## Where To Get Support ?
[support]: #where-to-get-support-
Enterprise Integration team can be reached at `ais-enterprise-integration-informatica@office365.wisc.edu` for any Secure Agent
support.
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment