Skip to content

Commit 40b2e9c

Browse files
lucasfcostalucasfcosta
committed
improve enterprise permission docs
1 parent 93b846c commit 40b2e9c

File tree

3 files changed

+129
-0
lines changed

3 files changed

+129
-0
lines changed

‎docs/enterprise/deployment-permissions.mdx‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Permissions - Self-hosted
3+
description: Permissions and setup required for deploying Briefer's enterprise version on Kubernetes.
4+
icon: passport
5+
---
6+
7+
Briefer's enterprise version requires specific permissions to function correctly on your Kubernetes cluster.
8+
9+
This page outlines everything you need to set up _before_ deploying the application.
10+
11+
There are four main areas where permissions are required:
12+
13+
1. Kubernetes: to install and run the Briefer application
14+
2. AWS ECR/IAM (IRSA): to pull enterprise images from Briefer's private ECR
15+
3. AWS Bedrock: to invoke foundation models for AI features
16+
4. RDS (optional): to connect to an external database (an RDS instance) for storing Briefer's data
17+
18+
Each of these is described in detail below.
19+
20+
## 1. Permissions for installing the Helm chart
21+
22+
You will need to ensure that you can install Helm charts on your Kubernetes cluster. This is a requirement for installing Briefer.
23+
24+
When installing Briefer's helm chart, you will need to ensure that you can grant the following permissions within the desired namespace:
25+
26+
```yaml
27+
rules:
28+
- apiGroups: ['']
29+
resources: ['pods/exec', 'services', 'persistentvolumeclaims']
30+
verbs: ['create', 'get']
31+
- apiGroups: ['apps']
32+
resources: ['statefulsets']
33+
verbs: ['create', 'get', 'watch', 'patch', 'list', 'delete']
34+
- apiGroups: ['']
35+
resources: ['pods']
36+
verbs: ['get', 'list']
37+
- apiGroups: ['']
38+
resources: ['secrets']
39+
verbs: ['create', 'patch', 'get', 'delete', 'list']
40+
```
41+
42+
<Note>
43+
Briefer uses this permissions to manage Jupyter runtimes and other components of the application, including secrets with environment variables for your Jupyter environments.
44+
</Note>
45+
46+
## 2. AWS Permissions to Pull Images from Briefer's ECR
47+
48+
Create an IAM role in your AWS account with the policy below. Make sure to replace that placeholder with the actual role name we will provide you.
49+
50+
```json
51+
{
52+
"Version": "2012-10-17",
53+
"Statement": [
54+
{
55+
"Effect": "Allow",
56+
"Action": "sts:AssumeRole",
57+
"Resource": "arn:aws:iam::999999999999:role/<we-will-provide-this-role>"
58+
}
59+
]
60+
}
61+
```
62+
63+
<Note>
64+
This permission allows the CronJob to assume a cross-account role in our AWS account and pull enterprise container images from our private ECR.
65+
66+
Briefer deploys a Kubernetes CronJob that keeps your image pull secret up to date. This CronJob uses IRSA (IAM Roles for Service Accounts) to authenticate with AWS.
67+
68+
Once the role is properly configured, the CronJob will handle authentication and secret updates automatically — no manual image pulls required.
69+
</Note>
70+
71+
## 3. AWS Permissions to Invoke Bedrock Models
72+
73+
To enable Briefer's AI capabilities, your deployment role must have permission to invoke specific foundation models on AWS Bedrock.
74+
75+
The following policy grants the required access:
76+
77+
```json
78+
{
79+
"Version": "2012-10-17",
80+
"Statement": [
81+
{
82+
"Effect": "Allow",
83+
"Action": [
84+
"bedrock:InvokeModel",
85+
"bedrock:InvokeModelWithResponseStream"
86+
],
87+
"Resource": [
88+
"arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-7-sonnet-20250219-v1:0"
89+
]
90+
},
91+
{
92+
"Effect": "Allow",
93+
"Action": "bedrock:ListFoundationModels",
94+
"Resource": "*"
95+
}
96+
]
97+
}
98+
```
99+
100+
<Note>
101+
Make sure that you enable the Bedrock service in your AWS account and that you have access to the models you want to use.
102+
</Note>
103+
104+
## 4. (Optional) Using a Managed RDS Database
105+
106+
Briefer supports running its internal database either inside the Kubernetes cluster or via an external RDS instance. We strongly recommend using RDS for production setups due to its improved reliability and performance.
107+
108+
To use RDS:
109+
110+
1. Provision a PostgreSQL instance in your AWS account
111+
2. Create a database
112+
3. Create a user with read/write permissions
113+
4. Save the connection string and credentials
114+
115+
You will later provide these values in Briefer’s Helm chart configuration.
116+
117+
We also recommend configuring periodic backups and snapshots for your RDS instance to ensure data durability.
118+
119+
<Note>
120+
Briefer does not require permissions to create or manage RDS resources directly - but someone in your organization must provision the database before deployment if you want to use RDS.
121+
</Note>

‎docs/introduction.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,13 @@ We recommend that you either sign-up for the cloud or deploy it yourself. That w
156156
## Enterprise-specific documentation
157157

158158
<CardGroup cols={2}>
159+
<Card
160+
title="Permissions - Self-hosted"
161+
icon="passport"
162+
href="./enterprise/deployment-permissions"
163+
>
164+
Permissions and setup required for deploying Briefer's enterprise version on Kubernetes.
165+
</Card>
159166
<Card
160167
title="SSO - Self-hosted"
161168
icon="lock"

‎docs/mint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@
9595
{
9696
"group": "Enterprise",
9797
"pages": [
98+
"enterprise/deployment-permissions",
9899
"enterprise/sso-self-hosted",
99100
"enterprise/datasource-identities",
100101
"enterprise/granular-permissions",

0 commit comments

Comments
 (0)