Self-managed Slack

Our Slack integration requires a Slack app, which needs to be configured in your own Slack workspace when using Cortex Self-Managed.

Setup instructions​

Create the app​

Use the following manifest to create a new Slack app in your workspace. Make sure to replace the URLs found in [] with the URLs you set up for your self-managed Cortex instance.

_metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: Cortex
  description: Manage your microservices
  background_color: "#d21285"
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: cortex
    always_online: true
  slash_commands:
    - command: /cortex
      url: https://[Cortex Backend URL]/api/internal/v1/slack/slash-command
      description: Cortex slash commands
      usage_hint: runbooks, docs, on-call, logs
      should_escape: false
oauth_config:
  redirect_urls:
    - https://[Cortex Frontend URL]/slack/redirect
  scopes:
    bot:
      - app_mentions:read
      - channels:join
      - channels:read
      - chat:write
      - chat:write.customize
      - chat:write.public
      - commands
      - im:history
      - reactions:read
      - users:read
      - users:read.email
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false

If your Cortex Self-Managed installation is not available from the public internet, the Slack Slash commands integration will not work, as Slack needs to be able to hit the Cortex API when a command is run.

Connect your Cortex instance​

You'll need to configure your on-prem deployment to be able to talk your Slack App.

1. Create a k8s secret and add the secret in your values.yaml file for the Helm chart. You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.

2. Add the follow key/values to the secret. Note that Kubernetes will base64-encode these values:

   • SLACK_CLIENT_ID

   • SLACK_CLIENT_SECRET

   • SLACK_SIGNING_SECRET

   • SLACK_SLASH_COMMAND_TOKEN (“Verification Token” seen in the Slack App page)

3. Restart your Cortex backend deployment.

Install the app​

Once your backend has restarted, you're ready to install the app.

Note: Make sure you're logged in on your Cortex application before triggering this install.

Navigate to https://slack.com/oauth/v2/authorize?client_id=[CLIENT ID]&scope=chat%3Awrite%2Ccommands%2Cchannels%3Ajoin%2Cchannels%3Aread%2Cusers%3Aread%2Cusers%3Aread.email&redirect_uri=[REDIRECT URL set in the manifest, URL ENCODED]. It may spin forever on this page, if you refresh you should see that it’s installed.

You'll know that it's set up correctly if there's a Team ID number visible in Settings → Slack in your Cortex app.

FAQ and Troubleshooting

What if I use a different secret manager?

If you use something other than the K8s secret manager, you don't need to base64-encode your credentials.

Where do I set my credentials?

You only need to set credentials in the backend.

Why are my slash commands failing?

If the backend is not publicly reachable (e.g., it's behind a firewall or on a private network), the commands will fail. Make sure the backend URL specified in your slash command configuration is publicly accessible. Slack must be able to reach the Cortex API at the /api/internal/v1/slack/slash-command endpoint in order to process slash commands.