How to use Rancher 2 WebSocket API?

Hi there

Rancher 2 is amazing, but unfortunately, for now, it lacks some documentation. As a complete newcomer to the world of Rancher, this can be a real hassle. For the past few hours I have been trying to interact with the WebSocket API, but with no luck. There are a handful of articles on this topic available on the internet, but they all cover version 1 of the Rancher API.

It would be really helpful if someone here could give me a little more insight in how the WebSocket API works, how authentication is performed, and which endpoints can be consumed.

Thanks in advance!



What are you trying to accomplish with the websocket API? What endpoint are you trying to hit?


Hi Craig

Thanks for replying!

My goal is to listen to the resource.change events sent over de WebSocket API, in order to dynamically update a 3rd-party JavaScript client. The endpoint I’m trying to hit is /v3/subscribe.

Did you ever get this issue resolved? I am also trying to use the Rancher 2.0 websocket API and was able to a connection but after a few a little while I am getting a socket closed with error 1006. I also noticed that the rancher ui is using web sockets as well and when I look at the request from the chrome dev tools it appears that the many ws connections are happening to url `/v3/subscribe?socketId=x’

do you know what the socketId is used for?


There’s not really much to this… You connect and start receiving change event objects.

Authentication is the same as the rest of the API, token in the Authorization header as basic or bearer (or R_SESS cookie instead, which the UI uses for all auth, your can’t set arbitrary headers in the browser ws client).

/v3/subscribe is for global level things (e.g. projects and clusters themselves)
/v3/clusters/<id>/subscribe for cluster level things (e.g. nodes)
/v3/projects/<id>/subscribe for project level things (e.g. workloads)

socketId is used by the UI to keep track of the connections and has no meaning to you or the server. It’s just a counter that goes up each time a websocket is opened.