Skip to content

Managing Resources

This guide explains how to create and configure resources in Raikoo. Resources represent remote compute environments that your workflows can connect to for executing operations, running commands, and accessing external systems.

Understanding Resources

Resources in Raikoo are organization-level entities that define connections to remote compute environments. They provide:

  • Centralized configuration - Define connections once and use them across multiple workflows
  • Flexible routing - Support for proxies, jump hosts, and complex network topologies
  • Multiple connection options - Define several ways to reach the same resource
  • Secure credential management - Use text replacements to reference secrets instead of embedding credentials

Resources are shared across all projects within an organization, making them ideal for infrastructure that serves multiple teams and workflows.

Accessing the Resources Page

To access resources in your organization:

  1. Navigate to your organization's dashboard
  2. Click on "Resources" in the main navigation menu
  3. You'll see a list of all resources configured for your organization

The Resources page displays:

  • Resource name - A descriptive identifier for each resource
  • Description - Optional details about the resource's purpose
  • Action buttons - Create, edit, duplicate, or delete resources

!!! note "Permissions Required" You need the organization.resources.view permission to view resources, and organization.resources.crud permission to create, edit, or delete them.

Creating a New Resource

To create a new resource:

  1. From the Resources page, click the "Create new Resource" button
  2. You'll be taken to the resource editor with two tabs:
    • General Information - Basic resource details
    • Connections - Network connection configurations

Configuring General Information

In the General Information tab:

  1. Resource Name (required)

    • Enter a descriptive name for your resource
    • Must start with a letter, underscore, or dollar sign
    • Can contain letters, numbers, underscores, dollar signs, spaces, and hyphens
    • Example: Corporate_Dev_Environment or Production AWS

  2. Description (optional)

    • Provide additional context about this resource
    • Describe its purpose, environment, or usage restrictions
    • Example: "Development servers behind corporate firewall"

!!! tip "Naming Best Practice" Use clear, descriptive names that indicate the environment and purpose, such as "Dev_DB_Server" or "Staging_API_Gateway". This helps team members quickly identify the right resource for their workflow.

Adding SSH Connections

Resources can have multiple connections, each representing a different way to access the remote system. Currently, Raikoo supports SSH connections with plans to add VNC, RDP, and custom protocols in the future.

Creating Your First Connection

  1. Navigate to the Connections tab
  2. Click the "Add Connection" button
  3. A dialog will open with the following fields:

Basic Connection Details

  • Connection Name (required)

    • A descriptive name for this specific connection
    • Example: "Primary SSH" or "Admin Access via Bastion"

  • Description (optional)

    • Additional details about this connection route
    • Example: "Routes through SOCKS5 proxy and bastion host"

  • Protocol (required, defaults to SSH)

    • Currently only SSH is available
    • Future protocols will include VNC, RDP, and others

Understanding Connection Routes

SSH connections in Raikoo use a connection route model that separates proxy configuration from hop configuration. A connection route consists of:

  • Proxy (optional) - An initial proxy server to route all traffic through
  • Hops (required, at least one) - A sequence of SSH connections from entry point to destination

Think of it as: Your Machine → [Proxy] → Hop 1 → Hop 2 → ... → Destination

Complete Example: SSH Connection with SOCKS5 Proxy and Jump Hosts

Let's create a realistic example for accessing an internal development server that requires:

  1. Routing through a corporate SOCKS5 proxy
  2. Connecting to a bastion host in a DMZ
  3. Hopping to the final internal development server

Scenario Details

You need to access dev-server-01.internal which is only accessible from within the corporate network. Your access path is:

  1. Your machine → SOCKS5 proxy (proxy.corp.example.com:1080)
  2. Proxy → Bastion host (bastion.corp.example.com)
  3. Bastion → Internal dev server (dev-server-01.internal)

Step 1: Configure the Proxy

After clicking "Add Connection" and entering the connection name:

  1. Toggle the "Use Proxy" switch to enable proxy configuration
  2. Configure the proxy settings:
    • Proxy Type: Select "SOCKS v5" from the dropdown
    • Proxy Host: proxy.corp.example.com
    • Proxy Port: 1080
    • Proxy Username: {{Secret.ProxyUsername}} (using a text replacement)
    • Proxy Password: {{Secret.ProxyPassword}} (using a text replacement)

!!! note "Proxy Types" Raikoo supports HTTP, HTTPS, SOCKS, SOCKS v4, and SOCKS v5 proxies. HTTPS proxies offer additional options for client certificates and CA validation.

Step 2: Configure the First Hop (Bastion Host)

The first hop configuration is automatically created. Configure it as follows:

  1. IP Address / Hostname: bastion.corp.example.com
  2. Username: admin
  3. Port: 22 (default SSH port)
  4. Authentication Method: Select "Private Key" (radio button)
  5. Private Key: {{Secret.BastionPrivateKey}}
    • Use a text replacement to reference a secret containing your SSH private key
    • Alternatively, paste the full private key (starts with -----BEGIN RSA PRIVATE KEY-----)
  6. Passphrase: {{Secret.BastionKeyPassphrase}} (if your key is encrypted)

!!! tip "Using Text Replacements" Text replacements like {{Secret.BastionPrivateKey}} reference secrets stored in your organization. This keeps sensitive credentials out of the resource configuration and makes them easier to rotate.

Step 3: Add the Second Hop (Internal Dev Server)

  1. Click the "Add Hop" button
  2. A new hop configuration section will appear labeled "Hop 2 (Final Destination)"
  3. Configure the second hop:
    • IP Address / Hostname: dev-server-01.internal
    • Username: developer
    • Port: 22
    • Authentication Method: Select "Password" (radio button)
    • Password: {{Secret.DevServerPassword}}

!!! info "Mixed Authentication Methods" Each hop can use a different authentication method. In this example, the bastion uses private key authentication while the internal server uses password authentication.

Step 4: Save the Connection

  1. Review your configuration:

    • SOCKS5 proxy at proxy.corp.example.com:1080
    • Hop 1: admin@bastion.corp.example.com (private key)
    • Hop 2: developer@dev-server-01.internal (password)

  2. Click "Add Connection" to save

You'll see your new connection displayed in the Connections tab with summary chips showing:

  • Protocol: SSH
  • IP Address: bastion.corp.example.com (first hop)
  • Port: 22
  • Username: admin
  • Auth type: Key Auth
  • Hop count: 2 hops
  • Proxy indicator: Via SOCKS5 Proxy

Step 5: Save the Resource

  1. Return to the General Information tab if you haven't set the resource name and description
  2. Click the "Save" button in the top toolbar
  3. Your resource is now available for use in workflows

Working with Multiple Connections

A single resource can have multiple named connections. This is useful for:

  • Redundant paths - Primary and backup routes to the same destination
  • Different access levels - Admin connections and read-only connections
  • Network-specific routes - Different paths for office vs. VPN vs. cloud networks
  • Testing and production - Separate connections for different environments on the same physical resource

Adding Additional Connections

  1. Navigate to the Connections tab
  2. Click "Add Connection"
  3. Follow the same process to configure a new connection route
  4. Give it a distinct name to differentiate it from other connections

Editing Existing Connections

  1. In the Connections tab, click the Edit icon (pencil) on the connection card
  2. Modify the connection settings as needed
  3. Click "Update Connection" to save changes

Deleting Connections

  1. Click the Delete icon (trash can) on the connection card
  2. Confirm the deletion when prompted
  3. The connection is immediately removed (requires saving the resource)

!!! warning "Deletion Warning" Deleting a connection that is currently in use by workflows will cause those workflows to fail when they attempt to use it. Always check workflow dependencies before removing connections.

Using Text Replacements for Credentials

Text replacements are a powerful feature for managing sensitive information. They allow you to reference values stored elsewhere instead of embedding them directly in the resource configuration.

Secret References

The most common use case is referencing secrets:

{{Secret.SecretName}}

You can use text replacements in any connection field:

  • Proxy credentials: {{Secret.ProxyUsername}}, {{Secret.ProxyPassword}}
  • SSH credentials: {{Secret.SSHPassword}}, {{Secret.SSHPrivateKey}}
  • Hostnames: {{Secret.ProductionHostname}}
  • Ports: {{Secret.SSHPort}}

Benefits of Text Replacements

  • Security - Credentials are stored in encrypted secrets, not in plain text
  • Centralization - Update a secret once and all resources using it are updated
  • Rotation - Easy credential rotation without modifying resource configurations
  • Flexibility - Use workflow variables and context for dynamic connections

!!! note "Creating Secrets" Secrets are managed at the organization level. You'll need to create the referenced secrets before they can be used in text replacements. See the Secrets documentation for details.

Connection Configuration Options

SSH Authentication Methods

Raikoo supports two SSH authentication methods:

  • More secure than password authentication
  • Supports RSA, ECDSA, and ED25519 keys
  • Optional passphrase for encrypted keys
  • Best practice for production environments

To use private key authentication:

  1. Select "Private Key" as the authentication method
  2. Paste your private key or use {{Secret.KeyName}}
  3. If your key is encrypted, provide the passphrase

Password Authentication

  • Simpler setup for systems that require it
  • Less secure than key-based authentication
  • Suitable for development or legacy systems

To use password authentication:

  1. Select "Password" as the authentication method
  2. Enter the password or use {{Secret.PasswordName}}

Proxy Configuration Options

Each proxy type has different configuration options:

HTTP/HTTPS Proxies

  • Standard corporate proxies
  • Support for username/password authentication
  • HTTPS proxies offer additional TLS options:
    • Client Certificate - For mutual TLS authentication
    • Client Key - Private key for client certificate
    • CA Certificate - Custom certificate authority
    • Reject Unauthorized - Enable/disable certificate validation

SOCKS Proxies

  • Lower-level proxying suitable for any TCP traffic
  • SOCKS v4 - Basic proxy protocol, no authentication
  • SOCKS v5 - Enhanced protocol with username/password authentication
  • SOCKS (generic) - Raikoo will attempt v5 first, then v4

Best Practices

Security

  • Always use secrets - Never embed passwords or private keys directly in configurations
  • Prefer private key authentication - More secure than passwords for SSH connections
  • Minimize hops - Use the fewest number of hops necessary to reduce attack surface
  • Use strong authentication - Enable passphrases on private keys
  • Regular credential rotation - Update secrets periodically

Organization

  • Descriptive naming - Use clear names that indicate purpose and environment
  • Document connections - Use descriptions to explain routing and access requirements
  • Consistent patterns - Establish naming conventions across your organization
  • Group by environment - Consider prefixes like "Prod_", "Dev_", "Staging_"

Connection Design

  • Test incrementally - When setting up multi-hop routes, test each hop individually first
  • Primary and backup - Create redundant connections for critical resources
  • Separate concerns - Use different resources for development, staging, and production
  • Environment-specific - Consider creating resources per environment rather than sharing

Performance Considerations

  • Network latency - Each hop adds latency; balance security with performance
  • Connection pooling - Workflows may reuse connections to reduce overhead
  • Proxy selection - Choose proxy types appropriate for your network requirements

Monitoring and Troubleshooting

Verifying Connection Configuration

Before using a resource in a workflow, verify:

  • All required fields are filled in
  • Hostnames are resolvable from your network
  • Ports are accessible
  • Credentials are correct
  • Text replacements reference existing secrets

Common Issues

Connection Timeouts

  • Verify proxy and host addresses are correct
  • Check firewall rules allow connections
  • Ensure ports are open
  • Test network connectivity from your execution environment

Authentication Failures

  • Confirm credentials are correct in referenced secrets
  • Check username matches the target system
  • For private keys, verify the format is correct (PEM format)
  • Ensure passphrases are provided for encrypted keys

Hop Chain Failures

  • Test each hop individually
  • Verify intermediate hosts can reach subsequent hops
  • Check network routing between hops
  • Confirm each hop has necessary credentials

Next Steps

Now that you've created and configured resources, you can:

  • Use resources in workflows - Reference resources in operations that require remote execution
  • Create operation templates - Build reusable operation templates that leverage your resources
  • Set up monitoring - Configure alerts for resource connectivity issues
  • Document your infrastructure - Maintain documentation about your resource topology

Resources provide a powerful foundation for building workflows that interact with your infrastructure. By properly configuring connections with appropriate security measures, you can safely automate tasks across your entire environment.