Metadata-Version: 2.5
Name: jupyter-deploy-tf-aws-ec2-jupyterlab
Version: 0.1.0rc2
Summary: Terraform template to deploy a single-user JupyterLab on an AWS EC2 instance, accessed via a local proxy with AWS-identity auth.
Project-URL: Homepage, https://github.com/jupyter-infra/jupyter-deploy
Project-URL: github, https://github.com/jupyter-infra/jupyter-deploy/tree/main/libs/jupyter-deploy-tf-aws-ec2-jupyterlab
Author-email: Jonathan Guinegagne <jggg@amazon.com>, Gaurav Bhanderig <bgrv@amazon.com>, Michael Chin <chnmch@amazon.com>, Andrii Ieroshenko <aieroshe@amazon.com>
License: MIT License
        
        Copyright (c) Amazon Web Services
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: boto3
Requires-Dist: boto3-stubs
Requires-Dist: mypy-boto3-dynamodb
Requires-Dist: mypy-boto3-ec2
Requires-Dist: mypy-boto3-ecr
Requires-Dist: mypy-boto3-eks
Requires-Dist: mypy-boto3-elbv2
Requires-Dist: mypy-boto3-inspector2
Requires-Dist: mypy-boto3-resourcegroupstaggingapi
Requires-Dist: mypy-boto3-s3
Requires-Dist: mypy-boto3-secretsmanager
Requires-Dist: mypy-boto3-ssm
Requires-Dist: mypy-boto3-sts
Description-Content-Type: text/markdown

# Jupyter Deploy AWS EC2 JupyterLab template

Terraform template that runs a **single-user JupyterLab** on a remote AWS EC2 instance,
reached from your laptop through the local `jupyter-deploy-client-proxy` over a pinned
self-signed TLS connection, authenticated with short-lived AWS-identity (STS) tokens.

**AWS credentials are the only prerequisite**.

```
jd init . -E terraform -P aws -I ec2 -T jupyterlab   # default template = aws:ec2:jupyterlab
jd config                                            # region, instance type, volume size
jd up                                                # provision instance + self-signed cert
jd open                                              # start the proxy and open the browser
```

## How it works

- **Data path:** the browser talks to a local proxy over `http://localhost`; the proxy
  talks to the instance's Traefik on `:443` over pinned self-signed TLS (the pin is on the
  cert, not the address, so a new public IP after a stop/start is a non-event).
- **Cert pin:** the instance generates a long-lived self-signed cert at boot (private key
  persisted on the EBS data volume) and publishes only the public PEM to an SSM parameter
  that `jd proxy connect-info` reads live.
- **Auth:** `jd proxy connect-info` mints a `k8s-aws-v1` STS-identity token; a ForwardAuth
  sidecar behind Traefik validates it (STS replay + ARN allowlist + `x-k8s-aws-id` binding).
  No shared secret is stored anywhere.
- **Network:** the security group allows inbound `:443` only (open to `0.0.0.0/0`); the access
  boundary is the pinned TLS cert plus the STS-identity token above, not the network layer.

## Managing access

The deploying identity is always authorized. To grant others (matched case-insensitively by bare
IAM name, scoped to this account), use the runtime commands — they recreate only the auth-sidecar
(~1-2s), leave JupyterLab running, and write the change back into the terraform variables so `jd up`
stays in sync:

- IAM **roles**: `jd teams add|remove|set|list <RoleName>...`
- IAM **users**: `jd users add|remove|set|list <name>...`

(`jd teams` → IAM roles, `jd users` → IAM users.) The `iam_role_names_allowlist` /
`iam_user_names_allowlist` variables are the source of truth — editing them and running `jd up` also
reconciles the allowlist, but restarts the whole app, so the commands above are preferred for routine
access changes. Because those commands write their change back into the variables, a later `jd up`
re-applies the same list rather than reverting it.

## New IAM permissions

The *local* CLI credentials need, in addition to the base SSM permissions:
`ec2:DescribeInstances` (resolve the instance IP) and `ssm:GetParameter` (read the cert pin). `jd host start`/`stop` additionally use `ec2:StartInstances` / `ec2:StopInstances`.

## License

MIT License. See [LICENSE](./LICENSE).
