OCI Roles

cloudspells.providers.oci.roles

Role-based security posture descriptors — re-exported from core abstractions.

Role and all predefined role instances are defined in cloudspells.core.abstractions.roles and re-exported here for backward compatibility. Import from either location; prefer the core path in provider-agnostic code:

# Provider-agnostic code
from cloudspells.core.abstractions import Role, APP_SERVER

# OCI-specific code (both forms work)
from cloudspells.providers.oci import APP_SERVER
from cloudspells.providers.oci.roles import APP_SERVER

Exports

Role: Security posture dataclass. INTERNET_EDGE: Predefined role for internet-facing resources. APP_SERVER: Predefined role for private-tier application servers. DATABASE: Predefined role for secure-tier databases. CACHE: Predefined role for private-tier caches and message brokers. MANAGEMENT: Predefined role for management-tier tooling.

APP_SERVER: Role = Role(subnet_tier=SUBNET_PRIVATE, egress_internet=True, egress_services=True, accept_management_ssh=True) module-attribute

Role for private-tier application servers.

Resources carrying this role are placed in the private subnet (NAT gateway + service gateway routes). Ambient rules include outbound access to the internet and to provider-managed services.

Example

from cloudspells.core.abstractions import APP_SERVER
from cloudspells.providers.oci import Nsg

web_nsg = Nsg("web-backend", role=APP_SERVER, vcn=vcn, compartment_id=compartment_id)

CACHE: Role = Role(subnet_tier=SUBNET_PRIVATE, egress_internet=True, egress_services=True, accept_management_ssh=True) module-attribute

Role for private-tier caches and message brokers (Redis, Memcached, Kafka).

Identical security posture to APP_SERVER — private subnet, internet egress, service egress. Provided as a semantic alias so that the intent of each resource is clear from its role name.

Example

from cloudspells.core.abstractions import CACHE
from cloudspells.providers.oci import Nsg

cache_nsg = Nsg("redis", role=CACHE, vcn=vcn, compartment_id=compartment_id)

DATABASE: Role = Role(subnet_tier=SUBNET_SECURE, egress_internet=False, egress_services=True, accept_management_ssh=True) module-attribute

Role for secure-tier databases.

Resources carrying this role are placed in the secure subnet (service gateway only — no NAT, no internet path).

Example

from cloudspells.core.abstractions import DATABASE
from cloudspells.providers.oci import Nsg

db_nsg = Nsg("database", role=DATABASE, vcn=vcn, compartment_id=compartment_id)

INTERNET_EDGE: Role = Role(subnet_tier=SUBNET_PUBLIC, egress_internet=False, egress_services=False, accept_management_ssh=False) module-attribute

Role for internet-facing load balancers and bastion hosts.

Resources carrying this role are placed in the public subnet (internet gateway route). Inbound ports are declared via the provider NSG ports= parameter.

accept_management_ssh=False because this role is the management entry point — it acts as the SSH source toward private-tier resources, not as an SSH target from another resource.

Example

from cloudspells.core.abstractions import INTERNET_EDGE
from cloudspells.providers.oci import Nsg

lb_nsg = Nsg("load-balancer", role=INTERNET_EDGE, ports=[HTTP, HTTPS], vcn=vcn,
             compartment_id=compartment_id)

MANAGEMENT: Role = Role(subnet_tier=SUBNET_MANAGEMENT, egress_internet=False, egress_services=True, accept_management_ssh=True) module-attribute

Role for management-tier monitoring agents, bastion service, and tooling.

Resources carrying this role are placed in the management subnet (service gateway only — same isolation as the secure tier, but logically separated for operational tooling).

Example

from cloudspells.core.abstractions import MANAGEMENT
from cloudspells.providers.oci import Nsg

mgmt_nsg = Nsg("monitoring", role=MANAGEMENT, vcn=vcn, compartment_id=compartment_id)

Role dataclass

Security posture descriptor for a class of networked resources.

A Role encodes the ambient network behaviour of a security group — the rules that every resource of this type needs regardless of which peers it communicates with. Directional traffic relationships are declared separately by the provider's NSG/security-group implementation.

Attributes:

Name	Type	Description
subnet_tier	SubnetTier	Which network tier resources carrying this role belong to. Used by compute spells to infer subnet placement when a role is supplied instead of an explicit subnet.
egress_internet	bool	True adds an all-protocol egress rule to 0.0.0.0/0 (outbound via NAT Gateway or equivalent). Suitable for private-tier app servers that call external APIs. Not set for DATABASE, MANAGEMENT, or INTERNET_EDGE.
egress_services	bool	True adds an all-protocol egress rule to the cloud provider's managed-services endpoint (OCI Service Gateway, AWS VPC Gateway, GCP Private Google Access). Required for any instance that calls provider-managed endpoints (object storage, container registry, etc.).
accept_management_ssh	bool	True causes the provider NSG implementation to automatically include an SSH (port 22) management channel from the upstream NSG in addition to the application port. Set False for roles where SSH access arrives through a separate channel (e.g. a bastion service session).

Example

from cloudspells.core.abstractions import Role
from cloudspells.core.abstractions import SUBNET_PRIVATE

# Custom role: private tier, internet + service egress, no SSH from upstream.
proxy = Role(
    subnet_tier=SUBNET_PRIVATE,
    egress_internet=True,
    egress_services=True,
    accept_management_ssh=False,
)

Source code in packages/cloudspells-core/src/cloudspells/core/abstractions/roles.py

@dataclass
class Role:
    """Security posture descriptor for a class of networked resources.

    A `Role` encodes the ambient network behaviour of a security group — the
    rules that every resource of this type needs regardless of which peers it
    communicates with.  Directional traffic relationships are declared
    separately by the provider's NSG/security-group implementation.

    Attributes:
        subnet_tier: Which network tier resources carrying this role belong to.
            Used by compute spells to infer subnet placement when a role is
            supplied instead of an explicit subnet.
        egress_internet: `True` adds an all-protocol egress rule to
            `0.0.0.0/0` (outbound via NAT Gateway or equivalent).  Suitable
            for private-tier app servers that call external APIs.  Not set for
            `DATABASE`, `MANAGEMENT`, or `INTERNET_EDGE`.
        egress_services: `True` adds an all-protocol egress rule to the cloud
            provider's managed-services endpoint (OCI Service Gateway, AWS
            VPC Gateway, GCP Private Google Access).  Required for any
            instance that calls provider-managed endpoints (object storage,
            container registry, etc.).
        accept_management_ssh: `True` causes the provider NSG implementation
            to automatically include an SSH (port 22) management channel from
            the upstream NSG in addition to the application port.  Set `False`
            for roles where SSH access arrives through a separate channel (e.g.
            a bastion service session).

    Example:
        ```python
        from cloudspells.core.abstractions import Role
        from cloudspells.core.abstractions import SUBNET_PRIVATE

        # Custom role: private tier, internet + service egress, no SSH from upstream.
        proxy = Role(
            subnet_tier=SUBNET_PRIVATE,
            egress_internet=True,
            egress_services=True,
            accept_management_ssh=False,
        )
        ```
    """

    subnet_tier: SubnetTier
    egress_internet: bool = False
    egress_services: bool = False
    accept_management_ssh: bool = True