Authentication for PuppyGraph to access AWS resources

Overview

PuppyGraph leverages AWS's native authentication ecosystem to provide secure, flexible, and easy-to-manage access to AWS resources like Amazon S3, AWS Glue Data Catalog, and other services. By using AWS's default credential provider chain, PuppyGraph eliminates the need for hardcoded credentials while providing seamless integration with AWS's security model.

Using Default Authentication in PuppyGraph

PuppyGraph uses the Default authentication method to automatically discover and use AWS credentials through the AWS Default Credential Provider Chain. This approach enhances security by eliminating hardcoded credentials and provides automatic adaptation to different deployment environments (EC2, EKS, containers, local development).

Simply configure your PuppyGraph resources with authentication set to Default.

Sample Configuration

S3 Storage Configuration

Parameter	Description	Example Value
S3 Authentication Type	Authentication method to use	Default
Region	AWS region for the S3 bucket	us-east-1

AWS Glue Metastore Configuration

Configuration	Description	Example Value
Glue Authentication Type	Authentication method to use	Default
Region	AWS region for the Glue catalog	us-east-1

Configuring Default Authentication for Different Environments

EC2 Instance Profile

If you are running PuppyGraph on an EC2 instance, you can use an EC2 Instance Profile to authenticate with AWS services. This is the most secure and recommended approach for EC2-based deployments.

PuppyGraph will automatically use the instance profile when configured with Default authentication.

To use instance profile authentication:

1. Create an IAM role with the necessary permissions for accessing AWS resources (see AWS IAM policies for required policies)
2. Attach the IAM role to your EC2 instance as an instance profile
3. Configure PuppyGraph to use default authentication

Environment Variables

You can set the standard AWS environment variables to provide credentials. This method is typically used for development or when running PuppyGraph in containerized environments where other credential methods are not available.

The standard AWS environment variables are:

• AWS_ACCESS_KEY_ID: Your AWS access key ID
• AWS_SECRET_ACCESS_KEY: Your AWS secret access key
• AWS_SESSION_TOKEN: Your AWS session token (required for temporary credentials)
• AWS_REGION: Your default AWS region

Example Docker run command with environment variables:

docker run -p 8081:8081 -p 8182:8182 -p 7687:7687 -d --name puppy --rm --pull=always \
    -e AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
    -e AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
    -e AWS_REGION=us-east-1 \
    puppygraph/puppygraph:stable

AWS Credentials File

PuppyGraph can use the standard AWS credentials file (~/.aws/credentials) when it's available in the container or host system. This method is commonly used in development environments.

Example ~/.aws/credentials file:

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[puppygraph]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

When using a credentials file, you can specify a profile using the AWS_PROFILE environment variable:

docker run -p 8081:8081 -p 8182:8182 -p 7687:7687 -d --name puppy --rm --pull=always \
    -e AWS_PROFILE=puppygraph \
    -v ~/.aws:/home/puppy/.aws:ro \
    puppygraph/puppygraph:stable

Amazon EKS with IAM Roles for Service Accounts (IRSA)

For Amazon EKS deployments, you can use IAM Roles for Service Accounts (IRSA) to provide AWS permissions to PuppyGraph pods without storing credentials in the cluster.

Example Kubernetes deployment with IRSA:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: puppygraph
spec:
  template:
    metadata:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/PuppyGraphRole
    spec:
      serviceAccountName: puppygraph
      containers:
      - name: puppygraph
        image: puppygraph/puppygraph:stable
        env:
        - name: AWS_REGION
          value: "us-east-1"

Amazon EKS Pod Identity

EKS Pod Identity is a newer, simpler method for providing AWS credentials to pods in Amazon EKS. It automatically provides AWS credentials to pods using the EKS Pod Identity Agent without requiring manual configuration of service accounts or trust relationships.

Example Kubernetes deployment with EKS Pod Identity:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: puppygraph
spec:
  template:
    spec:
      serviceAccountName: puppygraph
      containers:
      - name: puppygraph
        image: puppygraph/puppygraph:stable
        env:
        - name: AWS_REGION
          value: "us-east-1"
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: puppygraph
  annotations:
    eks.amazonaws.com/pod-identity-association: "arn:aws:eks::123456789012:podidentityassociation/a-abcdefghijklmnop1"

Both IRSA and EKS Pod Identity provide secure, temporary credentials to PuppyGraph without requiring credential management within the cluster.

Container Deployments

When running PuppyGraph in containers outside of Kubernetes, you can: - Mount AWS credentials file as a read-only volume - Use environment variables for credentials
- Leverage ECS Task Roles when running on Amazon ECS - Use EC2 Instance Profiles when running containers on EC2 instances

All of these methods work seamlessly with PuppyGraph's "Default" authentication configuration.

Assuming an IAM Role

For cross-account access or when you need to assume specific roles, you can configure PuppyGraph to assume a different IAM role. This method is useful when PuppyGraph needs to access resources in different AWS accounts or when following the principle of least privilege.

Here's a sample configuration for assuming an IAM role to access AWS Glue:

Configuration	Description	Example Value
Glue Authentication Type	Authentication method to use	Default
Region	AWS region for the Glue catalog	us-east-1
IAM Role ARN	ARN of the IAM role to assume	arn:aws:iam::123456789012:role/YourRole

Troubleshooting Authentication Issues

If you encounter authentication issues, verify:

1. Credentials are accessible: Ensure PuppyGraph can access the configured credential source
2. IAM permissions: Verify the role or user has the required permissions (see AWS IAM policies)
3. Region configuration: Ensure the AWS region is correctly specified
4. Network connectivity: Verify network access to AWS services
5. Credential precedence: Remember that the AWS SDK follows a specific order when looking for credentials

For detailed debugging of role assumptions, see Assumed Role Debug.