# AWS IAM Roles and Instance Profiles
## AWS IAM Roles
AWS IAM Roles are policy-based tokens with temporary credentials allowing a user
temporary access to AWS services and actions which the user is normally
not permitted to access. These users may be from different projects or even
different accounts. These roles can also be embedded into specific instances
allowing these instances access to the necessary actions.
The AWS IAM role consists of the following:
1. Permissions policy which give access to certain ZCS
supported AWS services or actions. This is defined in the
**Identity & Access > AWS Roles** view, **Attached Policies** tab.
2. Trust policy that defines the relationship between user per project
and this role. This is defined in the **Identity & Access > AWS Roles**
view, **Trust Policy** tab.
1. The nature of the relationship may be ‘allow’ which grants permission
to the specified users to assume the role, or ‘deny’ which prevents
these users from assuming the role.
2. This permission may be granted to multiple users of the same projects,
different projects within the same account, or even users of different
accounts.
3. The maximum session duration that can be requested when assuming this role.
### Viewing the AWS IAM Role List
1. Navigate to the **Identity & Access > AWS Roles** view. The defined AWS IAM
Role list will be displayed.
2. Select a specific role in the display list to view the following detailed
information:
1. **Events** - displays events related to the role.
2. **Attached Policies** - displays AWS API policies attached
to this role.
3. **Trust Policy** - displays entities allowed/denied to assume
this role.
### Creating an AWS IAM Role
1. Navigate to the **Identity & Access > AWS Roles** view.
2. In top toolbar, click **Create**.
3. In the **Create Role** dialog, **Details** tab, enter the following:
1. **Name** - name of the role AWS IAM Role to be defined.
2. **Description** - description of role..
3. **Max. Session Duration** - maximum time (in seconds) that a user can
assume this role.
- **Default:** 3600 seconds (1 hour).
- **Maximum:** 12 hours (43,200 second).
4. **Policies** - Select one or more managed AWS policies which define the
permissions of this role.
5. Click **Next**.
4. In the **Allow Assuming** tab, the trust policy is defined for this role.
Multiple trust policies can be defined by clicking **Add**. For each trust
policy, enter the following information:
1. **User/Service/Any** - defines for what user or service the role will
be applied.
- If **User** is selected, enter the project name and user name.
- If **Service** is selected, enter the service type. Currently, the
only available service type for the trust policy is **VM**.
- If **Any** is selected, enter project name. The trust policy will
be applied to all users.
2. Click **Next**.
5. In the **Deny Assuming** tab, users or services who can not assume this
role may be defined. This is an optional configuration and by default
there are no denied users or services. If defined, the same **user/service/any**
options described for the **allow assuming** step above are also available
for the **deny assuming** step.
**Note:** If the same user and project are defined for both **allow**
and **deny**, the ‘Deny’ prevails.
6. Click **Finish**. The new role will appear in the **Identity & Access > AWS Roles**
view.
### Deleting an AWS IAM Role
1. Navigate to the **Identity & Access > AWS Roles** view.
2. From the displayed list, select the role to be deleted.
3. From top toolbar, click **Delete**. The **Delete Role** dialog will open.
4. Click **Delete** to confirm. The role will be removed from
the **Identity & Access > AWS Roles** list.
### Modifying an AWS IAM Role
1. Navigate to the **Identity & Access > AWS Roles** view.
2. From the displayed list, select the role to be modified.
3. From top toolbar, click **Modify**. The **Modify Role** dialog will be
displayed. The following parameters can be modified:
1. **Max. Session Duration** - maximum time (in seconds) that a user can
assume this role.
2. **Policies** - managed policies which define the permissions of this role.
3. **Description**
4. Click **OK** to save the changes.
### Applying an AWS IAM Role via the CLI
When an AWS IAM role has been created and a policy attached, the role can
be applied via the Zadara Cloud Services CLI. This in turn will
generate the credentials needed to access the AWS services and actions
defined in the role. In order to assume a role you must know its ID.
1. Find the AWS IAM roles you want to use:
1. Run role iam-list:
Zadara Cloud Services @ user1/cloudacc1 > role iam-list
If you are a Member or Tenant Admin user, this command returns a list
of any roles created in the currently logged-in project, together with
the ID’s of all users who can assume these role(s).
2. To check if the entity_ids for any of the users is your own, use the
following command:
Zadara Cloud Services @ user1/cloudacc1 > user get-my-details
This will display your user_id along with your user_name.
3. Regardless of AWS IAM roles discovered, there may be roles available
which are not visible to you. To verify that you have the complete list
of roles available to you, it is recommended that a Zadara Admin user
does the following:
- List all of the AWS IAM Roles
```console
Zadara Cloud Services @ user1/cloudacc1 > role iam-list
```
All AWS IAM roles in the account will be displayed with the ID’s of
all users to which these roles are available.
- List all of the users
```console
Zadara Cloud Services @ user1/cloudacc1 > user list
```
This will display all of the users in the account with their names
and ID’s. It will now be possible to discover which roles are available
for which users.
2. Once you have the Role-ID, you can assume the AWS IAM role via
the ‘role assume-role **role_id** **session_name**’ command, where role_id
is supplied in the output above, and session_name is selected by the user.
```console
Zadara Cloud Services @ user1/cloudacc1 > role assume-role 565197da-2f13-48dc-b232-bdffc756b7f9 Session-1
```
This returns the following information:
```console
===================== ====================================
**access_key_id** 23515d96a5da4408821783e0b9aa6ff1
**created_at** 2019-03-10T20:55:42Z
**duration_seconds** 3600
**expires_at** 2019-03-10T21:55:42Z
**external_id** none
**policy_id** none
**project_id** fc268815422e471da6756c7918b03d01
**role_assumer** 5120ef807769455b822095497b55ffac
**role_id** 565197da-2f13-48dc-b232-bdffc756b7f9
**role_name** Role-2
**secret_access_key** 94d8a61f419b4edbb638abc399e7a420
**session_name** Session-1
**token** cd9b0253e0034cdd976c21c317c
===================== ====================================
```
3. Use the access_key_id, secret_access_key and token to access the AWS
services and actions.
## Instance Profiles
An instance profile is a container for an AWS IAM role. It can be used to
pass role information to an EC2 instance when the instance starts. When
an AWS IAM role, embedded in an instance profile, becomes attached to an
instance, its credentials become permanent.
The following actions can be performed with instance profiles:
### Viewing Instance Profiles
1. In the zCompute UI, go to **Compute > Instance Profiles**.
The instance profiles list is displayed.
2. Click an instance profile in the list to view its details.
The detailed instance profile view is displayed, with the option to
modify the instance profile by removing its associated role,
and the option to delete the instance profile.
### Creating an Instance Profile
To create an instance profile:
1. In the zCompute UI, go to **Compute > Instance Profiles**.
The instance profiles list is displayed.
2. In the top menu bar, click **Create**.
The **Create Instance Profile** dialog opens.
3. In the **Create Instance Profile** dialog, enter:
* **Name** - a name to identify the instance profile.
* **Role** - optionally select an AWS IAM role from the dropdown.
* Click **Finish**.
The new instance profile is displayed in the instance profiles list.
### Modifying an Instance Profile
An instance profile can be modified by changing its AWS IAM role.
This involves removing the current AWS IAM role from instance profile, and
adding a new role.
#### Removing an AWS IAM Role
1. In the zCompute UI, go to **Compute > Instance Profiles**.
The instance profiles list is displayed.
2. To modify an instance profile, click its entry in the list.
The detailed instance profile view is displayed.
3. In the top menu bar, click **Remove Role**.
The **Remove Role from Instance Profile** confirmation dialog opens.
4. Click **Delete** to remove the AWS IAM role from the instance profile.
#### Adding an AWS IAM Role
1. In the zCompute UI, go to **Compute > Instance Profiles**.
The instance profiles list is displayed.
2. To modify an instance profile, click its entry in the list.
The detailed instance profile view is displayed.
3. In the top menu bar, click **Add Role**.
The **Add Role to Instance Profile** dialog opens.
4. Select an AWS IAM role from the dropdown, to add to the instance profile.
5. Click **Ok**.
### Working with Instance Profiles via the CLI
#### Adding an AWS IAM Role into an Instance
Using instance profiles, it is possible to grant permissions to an instance to
access specific Zadara Cloud Services-supported AWS services. Although, in
the context of a user, role permissions are temporary, in the context of an
instance, the application is guaranteed to have credentials as long as the
instance profile is attached to the instance, and that instance profile has
a role embedded in it.
1. From the Zadara Cloud Services GUI, create an AWS IAM role together with
its AWS IAM policies and trust policies.
2. To create an instance profile, use the Zadara Cloud Services CLI command:
‘instance-profile create **name**’.
```console
Zadara Cloud Services @ user1/cloudacc1 > instance-profile create instance-profile-1
```
To view basic details about the newly created instance-profile, use
command *instance-profile -1*.
```console
============== ====================================
**id** dd56d017-0167-42b7-a130-8706d746493e
**name** instance-profile-1
**created_at** 2019-03-11T02:58:30Z
**path** /
**project_id** 4331358dff9b4c29aa53c982e92801f6
**roles** []
============== ====================================
```
3. Find the AWS IAM roles that you can embed in the instance profile as
follows:
1. Run role iam-list:
```console
Zadara Cloud Services @ user1/cloudacc1 > role iam-list
```
If you are a Member or Tenant Admin user, the above command returns a
list of any roles created in the currently logged-in project, together
with the ID’s of all users who can assume these role(s), as shown below.
2. To check if the entity_ids for any of the users is yours run the
following command:
```console
Zadara Cloud Services @ user1/cloudacc1 > user get-my-details
```
This will display your user_id along with your user_name.
4. Embed the role in the instance profile with the Zadara Cloud Services CLI
command ‘instance-profile add-role **instance_profile-id** **role_id**’, as
follows: (Take the instance_profile_id and the role_id from the steps above.)
**Note:** This command can be performed by a Member or Tenant admin if the
project of the role is the same as the logged-in project.
```console
Zadara Cloud Services @ user1/cloudacc1 > instance-profile add-role **dd56d017-0167-42b7-a130-8706d746493e** **565197da-2f13-48dc-b232-bdffc756b7f9**
```
5. Use the GUI to create an instance.
6. From the Zadara Cloud Services CLI using the CLI command “vm list” locate
the ID of the instance that you just created.
7. Since the instance profile operation is very sensitive to network latency
and cluster load, the system may time out before finishing the operation.
It is therefore recommended to increase the timeout on the metadata
service connection and/or allow retries. These can be configured inside
the VM that is connected to the instance-profile by setting the
following environment vars:
```console
AWS_METADATA_SERVICE_TIMEOUT >1
AWS_METADATA_SERVICE_NUM_ATTEMPTS >1
```
8. Using the Zadara Cloud Services CLI command ‘vm update **–instance-profile**
**INSTANCE_PROFILE** **vm_id**” attach the instance profile to the instance
you just created, as follows: (Take the instance_profile_id and the vm_id
from the steps above.) **Note:** The role and VM must be defined for
the same project. A Member user and Tenant Admin user can perform this
command if they are logged in to the same project as that of the role and
VM.
```default
Zadara Cloud Services @ user1/cloudacc1 > vm update -**-instance-profile** **dd56d017-0167-42b7-a130-8706d746493e d6ca69e7-1533-4740-9881-395d442719f5**
```
#### Instance Profiles CLI commands
1. To create an instance profile enter the following command:
```console
Zadara Cloud Services @ Account-1/Project-1 > instance-profile get
```
A variety of details about this instance profile will be displayed,
including it’s ID
2. To add an AWS IAM role to an instance profile:
1. Procure the role-id via the following command
```default
Zadara Cloud Services @ Account-1/Project-1 > role iam-list
```
The list of all IAM roles will be displayed, together with their ID’s.
2. Using the ID of the desired instance profile, returned from the first
command above, enter the following command:
```default
Zadara Cloud Services @ Account-1/Project-1 > instance-profile add-role
```
Only one role can be added to an instance profile.
3. To remove an AWS IAM role from an instance profile, enter the following
command:
```console
Zadara Cloud Services @ Account-1/Project-1 > instance-profile remove-role
```
4. To retrieve the entire list of Instance profiles in the cluster enter the
following command:
```console
Zadara Cloud Services @ Account-1/Project-1 > instance-profile list
```
The list of all instance profiles will be displayed, together with their ID’s.
5. To remove an Instance profile:
Using the ID of the desired instance profile retrieved above, enter the
following command:
```default
Zadara Cloud Services @ Account-1/Project-1 > instance-profile remove
```
6. To retrieve information about a specific instance profile:
Using the ID of the desired instance profile retrieved above,
enter the following command:
```default
Zadara Cloud Services @ Account-1/Project-1 > instance-profile get
```
A variety of details about this instance profile including its ID, will
be displayed.