docs/source/getting-started.rst
Getting Started
===============
.. include:: _warning.rst
.. include:: _links.rst
.. NOTE::
Use the online `policy converter <https://iam-floyd.readthedocs.io/en/latest/policy-converter.html>`__ to migrate any JSON policy to Floyd code!
Depending on your scenario, you need to either install/import ``iam-floyd`` or ``cdk-iam-floyd``:
.. code-block:: bash
# for use without AWS CDK use the iam-floyd package
npm install iam-floyd
# for use with CDK use the cdk-iam-floyd package
npm install cdk-iam-floyd
.. tabs::
.. code-tab:: ts
// for use without AWS CDK use the iam-floyd package
import { Statement } from 'iam-floyd';
// for use with CDK use the cdk-iam-floyd package
import { Statement } from 'cdk-iam-floyd';
.. code-tab:: js
// for use without AWS CDK use the iam-floyd package
const { Statement } = require('iam-floyd');
// for use with CDK use the cdk-iam-floyd package
const { Statement } = require('cdk-iam-floyd');
Both packages contain a statement provider for each AWS service, e.g. ``Ec2``. A statement provider is a class with methods for each and every available action, resource type and condition. Calling such method will add the action/resource/condition to the statement:
.. example:: action-single
Every method returns the statement provider, so you can chain method calls:
.. example:: action-chaining
The default effect of any statement is ``Allow``. To add some linguistic sugar you can explicitly call the ``allow()`` method:
.. example:: allow
Or ``deny()``:
.. example:: deny
To set an SID you can pass it as argument in the statement provider:
.. example:: sid
You can work with `access levels <access-levels_>`_. For every access level there are distinct methods available to add all related actions to the statement:
.. tabs::
.. group-tab:: JavaScript
- ``allListActions()``
- ``allReadActions()``
- ``allWriteActions()``
- ``allPermissionManagementActions()``
- ``allTaggingActions()``
.. example:: access-levels
To add actions based on regular expressions, use the method ``allMatchingActions()``.
.. IMPORTANT::
No matter in which language you use the package, the regular expressions need to be in `Perl/JavaScript literal style <regex_>`_ and need to be passed as strings!
.. example:: actions-matching
To add all actions (e.g. ``ec2:*``), call the ``allActions()`` method:
.. example:: actions-all
For every available condition key, there are ``if*()`` methods available.
.. example:: conditions
To add a condition not covered by the available methods, you can define just any condition yourself via ``if()``:
.. example:: conditions-raw
The default operator for conditions of type `String <string-operator_>`_ is StringLike.
Most of the ``if*()`` methods allow an optional operator as last argument:
.. example:: conditions-operator-string
Statements without principals, by default, apply to all resources. To limit to specific resources, add them via ``on*()``. For every resource type an ``on*()`` method exists:
.. example:: resource
If instead you have an ARN ready, use the ``on()`` method:
.. example:: resource-raw
To invert the policy you can use ``notAction()``, ``notResource()`` and ``notPrincipal()``:
.. example:: notAction
.. example:: notResource
.. example:: notPrincipal